First Fault Isolation

Diagnose Flink jobs that are restarting, crashing, or stuck in a failure loop. The current exception in recent logs is almost always a loop-sustaining side effect, not the root cause. Find the FIRST task failure (attempt #0) and read its throwableInformation.

Use this guide when fullRestarts > 0, downtime > 0, the Flink job keeps cycling RUNNING → STARTING → RUNNING, or recent logs show repeating exceptions without obvious cause.

#1 Rule

When a Flink job is in a restart loop, recent logs show loop iterations, NOT the root cause. Everything else — addSplitsBack, UnsupportedOperationException: Partial recovery is not supported, SSLException during restarts, connection errors after a stop — is a loop-sustaining side effect. The original trigger is in attempt #0’s throwableInformation field.

Methodology

Step 1: Find crash onset (binary search)

Restart loops can run for days or weeks. The “last 1h” log window will only show loop iterations. Find the hour where fullRestarts first transitioned from 0 → >0 by binary searching backward across 14 days using CloudWatch:

Halve the window until you isolate the hour where fullRestarts went from 0 to >0. If fullRestarts > 0 for the entire 14-day window, the job has never been stable on the current configuration.

In Flink 2.2+, use numRestarts (cumulative counter) — fullRestarts is removed.

Step 2: Find the last successful checkpoint or transition to RUNNING before crash onset

If the app has checkpointing enabled, you can look for the last time the application successfully took a checkpoint:

This gives the timestamp where the job was last healthy.

For apps without checkpointing, or using unaligned checkpointing, it is more reliable to identify the first time the app transitioned from a RUNNING state (see step 3).

Step 3: Find attempt #0 — the FIRST task failure

In the 30 seconds after the last successful checkpoint, fetch ALL log events (do not filter) and look for:

• "switched from RUNNING to" — the task status change event
• "#0 (" in the task name — #0 confirms attempt zero (first failure, not a loop iteration)
• "Recovering subtask" followed by "Triggering job failover" — the restart loop beginning

Step 4: Extract throwableInformation from attempt #0

MSF emits structured JSON logs. The actual exception and stack trace are in the throwableInformation field, NOT the message field. CloudWatch filter-log-events searches the raw log string, so a pattern like "JsonParseException" may not match if the exception is nested inside throwableInformation.

The reliable approach is to filter on "switched from RUNNING" then extract the field with jq:

Follow the Caused by chain downward, but the deepest exception is not automatically the root cause — it’s just where the stack trace ends. Often it is the root cause (a JsonParseException at a specific offset, an AmazonS3Exception: 403, a user-code NullPointerException at a named line). Sometimes it isn’t. Treat the deepest exception as the root cause only when it has specific, actionable context — a class.method() in user code, a connector message naming a resource and HTTP status, a parser pointing at a byte offset.

When the deepest exception is itself a symptom

Some exceptions terminate the stack trace but tell you almost nothing about why. They mean “the TaskManager / job stopped responding,” not “here is what went wrong.” When you see one of these as the deepest Caused by, stop reading stack traces and pivot to metrics and live diagnostics — the cause is no longer in the logs, it’s in what was happening to the JVM or the cluster at that moment.

The pivot itself: re-anchor on FIRST_FAILURE_MS and pull a tight window of metrics and JM/TM logs around it.

Concrete pattern to look for: oldGenerationGCTime rising sharply or heapMemoryUtilization near 100% in the minutes before a heartbeat timeout = GC pressure / impending OOM, not a network issue. containerCPUUtilization pinned at the limit before a heartbeat timeout = CPU starvation, also not a network issue. If neither is true, suspect a real network event (VPC issue, ENI exhaustion) and check the EC2/VPC side.

Only after you have a coherent story across logs and metrics is it safe to call the root cause. If you can’t get there from the data, say so explicitly in the report rather than promoting a symptom.

Loop-Sustainer vs Original Trigger

Kinesis Source FLIP-27 Recovery Blocker

The KinesisStreamsSource (FLIP-27) does not support partial recovery. Any task failure with this source becomes an infinite restart loop because every restart attempt fails with UnsupportedOperationException from addSplitsBack(). The original cause in attempt #0 may have been transient (a single bad record, a momentary network blip), but the loop is permanent until you escape it.

Escape procedure (causes reprocessing or data loss — confirm with user):

1. Fix the root cause from attempt #0
2. Stop the application with --force
3. Poll until READY
4. Start with ApplicationRestoreType=SKIP_RESTORE_FROM_SNAPSHOT

Diagnostic Anchors (Stack Trace Reading)

Flink Dashboard for Live Diagnosis

When the Flink job is running (not stuck restarting), use the Flink Dashboard REST API for thread dumps, per-vertex backpressure, and execution plan analysis. Get a pre-signed URL:

Authenticate by curling the URL with -c cookie.jar -L, then use ${BASE}flinkdashboard/ as the API base. Useful endpoints:

create-application-presigned-url fails on non-RUNNING applications.

Thread Dump Patterns

Job Graph Anti-Patterns (from plan and subtasks endpoints)

Mandatory Report Format

When delivering diagnosis to the user, structure it as:

State transitions (RUNNING → FAILED, Task failed, Restarting job) are always symptoms. Never report a state transition as a root cause.

Common Mistakes

References

• MSF Troubleshooting Guide (opens in a new tab)
• Flink REST API (opens in a new tab)
• FLIP-27: Refactor Source Interface (opens in a new tab)