apache/seatunnel · error · CommandExecuteException

Unsupported checkpoint history status %s

Error message

Unsupported checkpoint history status %s

What it means

ClientExecuteCommand.execute parses the --checkpoint-history-status CLI option into the CheckpointStatus enum via CheckpointStatus.valueOf on the uppercased value. When the value does not match any enum constant, a CommandExecuteException wrapping the raw IllegalArgumentException is thrown with the offending value in the message. This guards the job-submission client against invalid checkpoint history filter input before querying the engine.

Source

Thrown at seatunnel-core/seatunnel-starter/src/main/java/org/apache/seatunnel/core/starter/seatunnel/command/ClientExecuteCommand.java:166

                                                clientCommandArgs.getCheckpointOverviewJobId()));
                System.out.println(JsonUtils.toJsonString(overview));
            } else if (null != clientCommandArgs.getCheckpointHistoryJobId()) {
                Long historyJobId = Long.parseLong(clientCommandArgs.getCheckpointHistoryJobId());
                Integer pipelineId = clientCommandArgs.getCheckpointHistoryPipeline();
                int limit =
                        clientCommandArgs.getCheckpointHistoryLimit() == null
                                ? 20
                                : clientCommandArgs.getCheckpointHistoryLimit();
                CheckpointStatus status = null;
                if (clientCommandArgs.getCheckpointHistoryStatus() != null) {
                    try {
                        status =
                                CheckpointStatus.valueOf(
                                        clientCommandArgs
                                                .getCheckpointHistoryStatus()
                                                .toUpperCase());
                    } catch (IllegalArgumentException ex) {
                        throw new CommandExecuteException(
                                String.format(
                                        "Unsupported checkpoint history status %s",
                                        clientCommandArgs.getCheckpointHistoryStatus()),
                                ex);
                    }
                }
                List<CheckpointHistoryEntry> history =
                        engineClient
                                .getJobClient()
                                .getCheckpointHistory(historyJobId, pipelineId, limit, status);
                System.out.println(JsonUtils.toJsonString(history));
            } else if (null != clientCommandArgs.getSavePointJobId()) {
                engineClient
                        .getJobClient()
                        .savePointJob(Long.parseLong(clientCommandArgs.getSavePointJobId()));
            } else {
                Path configFile = FileUtils.getConfigPath(clientCommandArgs);
                checkConfigExist(configFile);

View on GitHub (pinned to cf67b549a7)

Solutions

1. Use an exact CheckpointStatus enum constant name (uppercase, e.g. RUNNING, FAILED, CANCELED, COMPLETED) for --checkpoint-history-status.
2. Inspect the CheckpointStatus enum in the seatunnel-engine module to list valid values for your version.
3. If migrating from an older version, update scripts to the renamed enum constants.

Example fix

// before
seatunnel.sh -C ... -Chs completed
// after
seatunnel.sh -C ... -Chs COMPLETED

const VALID_STATUS = ["RUNNING", "FAILED", "CANCELED", "COMPLETED"]; // mirror CheckpointStatus enum
if (checkpointHistoryStatus && !VALID_STATUS.includes(checkpointHistoryStatus.toUpperCase())) {
  throw new Error("checkpoint-history-status must be one of: " + VALID_STATUS.join(", "));
}

function isCheckpointStatus(v) { return ["RUNNING","FAILED","CANCELED","COMPLETED"].includes(v.toUpperCase()); }

try { client.execute(); } catch (CommandExecuteException e) { if (e.getMessage().startsWith("Unsupported checkpoint history status")) { System.err.println("Use a valid CheckpointStatus value: " + e.getMessage()); } else { throw e; } }

When it happens

Trigger: Submitting a job with -Chs/--checkpoint-history-status set to a string that is not a CheckpointStatus constant (e.g. 'completed' instead of 'COMPLETED', or 'running'). The throw occurs in ClientExecuteCommand.execute right after getCheckpointHistoryStatus() is read.

Common situations: Using lowercase or human-friendly status names that differ from the enum constants; passing a status from an older SeaTunnel version whose enum constants were renamed; scripting with a variable containing an invalid status.

Related errors

• Plugin type must be one of: [source, sink, transform]
• Invalid --status ${status}; expected PENDING, SENDING, ACKED
• Unknown checkpoint type:
• prepare method is not supported
• Unknown MetalakeClient type:

AI-assisted analysis of apache/seatunnel@cf67b549a7 (2026-09-10). Data as JSON: /api/errors/2f849b2170843a3e. Report an issue: GitHub.