{"record":{"id":"f6bc9819f16c96ad","repo":"apache/flink","slug":"checkpointinfo-getfailurecause","errorCode":null,"errorMessage":"{checkpointInfo.getFailureCause()}","messagePattern":"\\{checkpointInfo\\.getFailureCause\\(\\)\\}","errorType":"exception","errorClass":"CompletionException","httpStatus":null,"severity":"error","filePath":"flink-clients/src/main/java/org/apache/flink/client/program/rest/RestClusterClient.java","lineNumber":573,"sourceCode":"        checkpointTriggerMessageParameters.jobID.resolve(jobId);\n\n        final CompletableFuture<TriggerResponse> responseFuture =\n                sendRequest(\n                        checkpointTriggerHeaders,\n                        checkpointTriggerMessageParameters,\n                        new CheckpointTriggerRequestBody(checkpointType, null));\n\n        return responseFuture\n                .thenCompose(\n                        checkpointTriggerResponseBody -> {\n                            final TriggerId checkpointTriggerId =\n                                    checkpointTriggerResponseBody.getTriggerId();\n                            return pollCheckpointAsync(jobId, checkpointTriggerId);\n                        })\n                .thenApply(\n                        checkpointInfo -> {\n                            if (checkpointInfo.getFailureCause() != null) {\n                                throw new CompletionException(checkpointInfo.getFailureCause());\n                            }\n                            return checkpointInfo.getCheckpointId();\n                        });\n    }\n\n    @Override\n    public CompletableFuture<String> triggerDetachedSavepoint(\n            final JobID jobId,\n            final @Nullable String savepointDirectory,\n            final SavepointFormatType formatType) {\n        return triggerSavepoint(jobId, savepointDirectory, false, formatType, true);\n    }\n\n    @Override\n    public CompletableFuture<CoordinationResponse> sendCoordinationRequest(\n            JobID jobId, String operatorUid, CoordinationRequest request) {\n        ClientCoordinationHeaders headers = ClientCoordinationHeaders.getInstance();\n        ClientCoordinationMessageParameters params = new ClientCoordinationMessageParameters();","sourceCodeStart":555,"sourceCodeEnd":591,"githubUrl":"https://github.com/apache/flink/blob/2f3c205e9266cb30240eb7f4fdab15cad629a70f/flink-clients/src/main/java/org/apache/flink/client/program/rest/RestClusterClient.java#L555-L591","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Read the checkpointInfo.getFailureCause() message — it contains the actual server-side error (e.g., 'Checkpoint expired before completing').","Verify checkpoint storage configuration (state.checkpoints.dir) is valid and writable.","Ensure the job has checkpointing enabled and the checkpoint type is supported.","If checkpoint timeout, increase execution.checkpointing.interval and execution.checkpointing.timeout."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try {\n    long checkpointId = client.triggerCheckpoint(jobId, CheckpointType.FULL_CHECKPOINT).get();\n} catch (ExecutionException e) {\n    Throwable cause = ExceptionUtils.stripExecutionException(e);\n    // cause contains the server-side checkpoint failure reason\n    log.error(\"Checkpoint trigger failed: {}\", cause.getMessage());\n}","preventionTips":["Verify checkpoint storage directory is writable before triggering.","Ensure checkpointing is enabled on the job.","Monitor checkpoint metrics to catch degrading checkpoint performance early."],"tags":["checkpoint","rest-client","async-operation"],"backgroundTag":null,"analyzedSha":"2f3c205e9266cb30240eb7f4fdab15cad629a70f","analyzedAt":"2026-08-14T08:48:24.518Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}