apache/flink · error · CompletionException

{checkpointInfo.getFailureCause()}

Error message

{checkpointInfo.getFailureCause()}

What it means

Thrown when a checkpoint trigger operation completes but the JobManager reports a non-null failure cause in the CheckpointInfo response. After triggering a checkpoint via the REST API and polling its status, if the server-side checkpoint failed (e.g., checkpoint declined, storage error), the stored failure cause is rethrown as a CompletionException.

Source

Thrown at flink-clients/src/main/java/org/apache/flink/client/program/rest/RestClusterClient.java:573

        checkpointTriggerMessageParameters.jobID.resolve(jobId);

        final CompletableFuture<TriggerResponse> responseFuture =
                sendRequest(
                        checkpointTriggerHeaders,
                        checkpointTriggerMessageParameters,
                        new CheckpointTriggerRequestBody(checkpointType, null));

        return responseFuture
                .thenCompose(
                        checkpointTriggerResponseBody -> {
                            final TriggerId checkpointTriggerId =
                                    checkpointTriggerResponseBody.getTriggerId();
                            return pollCheckpointAsync(jobId, checkpointTriggerId);
                        })
                .thenApply(
                        checkpointInfo -> {
                            if (checkpointInfo.getFailureCause() != null) {
                                throw new CompletionException(checkpointInfo.getFailureCause());
                            }
                            return checkpointInfo.getCheckpointId();
                        });
    }

    @Override
    public CompletableFuture<String> triggerDetachedSavepoint(
            final JobID jobId,
            final @Nullable String savepointDirectory,
            final SavepointFormatType formatType) {
        return triggerSavepoint(jobId, savepointDirectory, false, formatType, true);
    }

    @Override
    public CompletableFuture<CoordinationResponse> sendCoordinationRequest(
            JobID jobId, String operatorUid, CoordinationRequest request) {
        ClientCoordinationHeaders headers = ClientCoordinationHeaders.getInstance();
        ClientCoordinationMessageParameters params = new ClientCoordinationMessageParameters();

View on GitHub (pinned to 2f3c205e92)

Solutions

1. Read the checkpointInfo.getFailureCause() message — it contains the actual server-side error (e.g., 'Checkpoint expired before completing').
2. Verify checkpoint storage configuration (state.checkpoints.dir) is valid and writable.
3. Ensure the job has checkpointing enabled and the checkpoint type is supported.
4. If checkpoint timeout, increase execution.checkpointing.interval and execution.checkpointing.timeout.

try {
    long checkpointId = client.triggerCheckpoint(jobId, CheckpointType.FULL_CHECKPOINT).get();
} catch (ExecutionException e) {
    Throwable cause = ExceptionUtils.stripExecutionException(e);
    // cause contains the server-side checkpoint failure reason
    log.error("Checkpoint trigger failed: {}", cause.getMessage());
}

When it happens

Trigger: Calling triggerCheckpoint(jobId, checkpointType) when the checkpoint cannot complete — e.g., checkpoint storage is unavailable, the job has no checkpointing configured, or an operator throws during snapshot.

Common situations: Checkpoint directory (hdfs:// or s3://) is not writable or does not exist; checkpoint interval is too aggressive and operators cannot keep up; RocksDB state backend misconfiguration; job does not have checkpointing enabled but a manual trigger was attempted.

Related errors

• {savepointInfo.getFailureCause()}
• {asynchronousOperationInfo.getFailureCause()}
• Failed to serialize ExecutionPlan.
• Failed to get the FileSystem of artifact {artifactFilePath}.
• Failed to submit ExecutionPlan.

AI-assisted analysis of apache/flink@2f3c205e92 (2026-08-14). Data as JSON: /api/errors/f6bc9819f16c96ad. Report an issue: GitHub.