{"record":{"id":"c7fe1b5dd84c8642","repo":"apache/seatunnel","slug":"restore-with-checkpoint-requires-a-numeric-jobid","errorCode":null,"errorMessage":"--restore-with-checkpoint requires a numeric jobId, got: ${value}","messagePattern":"--restore-with-checkpoint requires a numeric jobId, got: (.+?)","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-core/seatunnel-starter/src/main/java/org/apache/seatunnel/core/starter/seatunnel/args/ClientCommandArgs.java","lineNumber":216,"sourceCode":"        if (encrypt) {\n            return new ConfEncryptCommand(this);\n        }\n        if (decrypt) {\n            return new ConfDecryptCommand(this);\n        }\n        return new ClientExecuteCommand(this);\n    }\n\n    private String normalizeNumericJobId(\n            String value, String blankMessage, String invalidMessagePrefix) {\n        String trimmed = value.trim();\n        if (trimmed.isEmpty()) {\n            throw new IllegalArgumentException(blankMessage);\n        }\n        try {\n            Long.parseLong(trimmed);\n        } catch (NumberFormatException e) {\n            throw new IllegalArgumentException(invalidMessagePrefix + value, e);\n        }\n        return trimmed;\n    }\n\n    public DeployMode getDeployMode() {\n        return DeployMode.CLIENT;\n    }\n\n    public static class DryRunConverter implements IStringConverter<DryRun> {\n        @Override\n        public DryRun convert(String value) {\n            if (value == null || value.trim().isEmpty()) {\n                throw new IllegalArgumentException(\"Dry-run mode must not be empty.\");\n            }\n            String trimmed = value.trim();\n            if (DryRun.STATIC.getName().equalsIgnoreCase(trimmed)\n                    || DryRun.STATIC.name().equalsIgnoreCase(trimmed)) {\n                return DryRun.STATIC;","sourceCodeStart":198,"sourceCodeEnd":234,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-core/seatunnel-starter/src/main/java/org/apache/seatunnel/core/starter/seatunnel/args/ClientCommandArgs.java#L198-L234","documentation":"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.","triggerScenarios":"Passing a non-numeric jobId, e.g. --restore-with-checkpoint my-job-name, a UUID, or a jobId containing whitespace/letters; also blank strings.","commonSituations":"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.","solutions":["Pass the numeric jobId (e.g. --restore-with-checkpoint 912345678901234567)","Get the numeric job id from the job list/REST API instead of the job name","If you need named jobs, use --name for display and keep the auto-generated numeric id for restore"],"exampleFix":"// before\n--restore-with-checkpoint my_etl_job\n// after\n--restore-with-checkpoint 912345678901234567","handlingStrategy":"validation","validationCode":"String jobId = \"1234567890\"; // example\nif (jobId == null || jobId.trim().isEmpty() || !jobId.trim().matches(\"\\\\d+\")) {\n    throw new IllegalArgumentException(\"--restore-with-checkpoint requires a numeric jobId\");\n}\nLong.parseLong(jobId.trim());","typeGuard":"boolean isNumericJobId(String v) {\n    return v != null && v.trim().matches(\"\\\\d+\");\n}","tryCatchPattern":"try {\n    client.submit(args);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().contains(\"requires a numeric jobId\")) {\n        log.error(\"Pass the numeric job id, not the job name: \" + e.getMessage());\n    }\n}","preventionTips":["Fetch the numeric job id from the job list/REST API, not the display name","Remember custom string job names cannot be used with --restore-with-checkpoint","Validate ids with a digits-only regex in wrapper scripts"],"tags":["cli","job-id","validation"],"backgroundTag":"invalid-argument-format","analyzedSha":"cf67b549a7a6c35fa0beb12d83c62892427ea919","analyzedAt":"2026-09-10T21:44:55.265Z","contentChangedAt":"2026-09-10T21:44:55.265Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}