apache/seatunnel · error · IllegalArgumentException

--restore-with-checkpoint requires a numeric jobId, got: ${v

Error message

--restore-with-checkpoint requires a numeric jobId, got: ${value}

What it means

normalizeNumericJobId validates that a jobId supplied with --restore-with-checkpoint consists only of digits (parseable as a Long). If the value is blank a blank message is thrown; if it is non-numeric an IllegalArgumentException with '--restore-with-checkpoint requires a numeric jobId, got: <value>' is thrown, wrapping the NumberFormatException.

Source

Thrown at seatunnel-core/seatunnel-starter/src/main/java/org/apache/seatunnel/core/starter/seatunnel/args/ClientCommandArgs.java:216

        if (encrypt) {
            return new ConfEncryptCommand(this);
        }
        if (decrypt) {
            return new ConfDecryptCommand(this);
        }
        return new ClientExecuteCommand(this);
    }

    private String normalizeNumericJobId(
            String value, String blankMessage, String invalidMessagePrefix) {
        String trimmed = value.trim();
        if (trimmed.isEmpty()) {
            throw new IllegalArgumentException(blankMessage);
        }
        try {
            Long.parseLong(trimmed);
        } catch (NumberFormatException e) {
            throw new IllegalArgumentException(invalidMessagePrefix + value, e);
        }
        return trimmed;
    }

    public DeployMode getDeployMode() {
        return DeployMode.CLIENT;
    }

    public static class DryRunConverter implements IStringConverter<DryRun> {
        @Override
        public DryRun convert(String value) {
            if (value == null || value.trim().isEmpty()) {
                throw new IllegalArgumentException("Dry-run mode must not be empty.");
            }
            String trimmed = value.trim();
            if (DryRun.STATIC.getName().equalsIgnoreCase(trimmed)
                    || DryRun.STATIC.name().equalsIgnoreCase(trimmed)) {
                return DryRun.STATIC;

View on GitHub (pinned to cf67b549a7)

Solutions

  1. Pass the numeric jobId (e.g. --restore-with-checkpoint 912345678901234567)
  2. Get the numeric job id from the job list/REST API instead of the job name
  3. If you need named jobs, use --name for display and keep the auto-generated numeric id for restore

Example fix

// before
--restore-with-checkpoint my_etl_job
// after
--restore-with-checkpoint 912345678901234567
Defensive patterns

Strategy: validation

Validate before calling

String jobId = "1234567890"; // example
if (jobId == null || jobId.trim().isEmpty() || !jobId.trim().matches("\\d+")) {
    throw new IllegalArgumentException("--restore-with-checkpoint requires a numeric jobId");
}
Long.parseLong(jobId.trim());

Type guard

boolean isNumericJobId(String v) {
    return v != null && v.trim().matches("\\d+");
}

Try / catch

try {
    client.submit(args);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("requires a numeric jobId")) {
        log.error("Pass the numeric job id, not the job name: " + e.getMessage());
    }
}

Prevention

When it happens

Trigger: Passing a non-numeric jobId, e.g. --restore-with-checkpoint my-job-name, a UUID, or a jobId containing whitespace/letters; also blank strings.

Common situations: Users passing the job NAME instead of the numeric job ID; copying a job id from UI display strings that include prefixes; jobs created with string custom job names cannot be used with this flag.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

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