Troubleshooting

Ordered roughly by how often they come up. If none of this matches, mail support@peruns.cloud — a real person reads it.

My job says RUNNING but nothing is happening

Check consumer lag (Kafka tab) and busy time (Grafana → PerunsCloud — Flink).

• Lag growing, busy time near 1000ms/s → the job is the bottleneck. Add parallelism, and remember slots must cover it (see below).
• Lag growing, busy time low → the job is waiting on something external, usually a sink.
• Lag flat and near zero → the job is keeping up and the problem is upstream: check whether anything is producing.

My job is stuck in PENDING or never starts

Almost always one of two things:

Not enough task slots. Parallelism must be ≤ TaskManager replicas × slots per TaskManager. Flink accepts a job that asks for more, deploys it, and then waits forever. The pre-flight check catches this at submit; if you see it at runtime, the job predates that check.

Not enough capacity. The environment has a vNode budget, and pods that do not fit pend rather than evicting anything. Add vNodes, or lower the job's footprint.

Checkpoints are failing

The job runs, then fails periodically. Look at checkpoint duration in Grafana first — a rising line before the failures means state is growing faster than it can be written.

If checkpoints fail from the very first attempt, the destination is usually the problem rather than the job. Confirm the environment has state storage configured (the checkpoint browser on the job page lists what has actually been written).

Kafka: "UNKNOWN_TOPIC_OR_PARTITION"

Topic auto-creation is off on purpose. Create the topic from the Kafka tab — a silently auto-created topic would have one partition and none of the retention or naming guardrails the tab enforces, which is worse than an error.

Kafka: my client cannot connect from my laptop

You need the tunnel running — brokers are not on the public internet. See Connect your app to Kafka. If cloudflared access tcp is running and the client still fails, the usual cause is pointing the client at the cluster bootstrap address instead of localhost:9092.

Logs are empty in the History tab

History comes from log storage and is retained for as long as you configured (7 days by default). Two honest possibilities:

• The job genuinely wrote nothing in that window. Widen the time range.
• History is unavailable — the tab says so explicitly when that is the case. The Live tab still works, because it reads from the pods directly.

We separate those two messages deliberately: "we cannot search" and "there is nothing to find" are different facts, and treating them as one sends people hunting a bug in their own job.

Everything shows as offline / unreachable

The cluster agent is how the dashboard sees inside your environment. When it is unreachable, jobs, logs and Kafka all report "unknown" rather than pretending.

This is usually transient (a node restart, a tunnel reconnect). If it lasts more than a few minutes, the environment itself may be suspended — check its status — or something is wrong on our side, in which case we are already looking; mail support anyway, it helps.

I suspended my environment and my Kafka messages are gone

Expected, and worth saying plainly: suspend deletes the compute, brokers included, and their disks go with it. Topics, credentials and configuration come back on resume. Messages do not. Flink state in S3 survives.

If you need messages to survive a suspend, write them from Flink to S3 — that is the durable tier, and it is what suspend is designed around.

My bill is higher than I expected

Every environment's cost is capacity you allocated: vNodes for Flink, plus 6 more if you enabled Kafka. The environment page shows the split. Nothing is metered after the fact — if a number surprised you, it is a number that was allocated, and you can reduce it by removing capacity or suspending the environment.