apache/seatunnel · error · IllegalArgumentException

Please provide jobId when start with save point.

Error message

Please provide jobId when start with save point.

What it means

SeaTunnel's REST job submission supports resuming a job from an existing save point, but a save point is keyed by the original jobId. The REST endpoint refuses to start with a save point when the jobId parameter is missing, because it cannot know which saved state to restore. It is thrown as an IllegalArgumentException during request validation in submitJob before any job is created.

Source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/rest/service/JobInfoService.java:394

                job -> {
                    handleStopJob(job, getSeaTunnelServer(false), nodeEngine.getNode());
                    jsonResponse.add(
                            new JsonObject()
                                    .add(RestConstant.JOB_ID, (Long) job.get(RestConstant.JOB_ID)));
                });

        return jsonResponse;
    }

    public JsonObject submitJob(Map<String, String> requestParams, byte[] requestBody) {

        if (requestParams.containsKey(RestConstant.DRY_RUN)
                && requestParams.get(RestConstant.DRY_RUN) != null) {
            throw new IllegalArgumentException("Dry-run is only supported via CLI");
        }
        if (Boolean.parseBoolean(requestParams.get(RestConstant.IS_START_WITH_SAVE_POINT))
                && requestParams.get(RestConstant.JOB_ID) == null) {
            throw new IllegalArgumentException("Please provide jobId when start with save point.");
        }
        validateCheckpointRestoreRequest(requestParams);
        Config config;
        ConfigFormat configFormat = ConfigFormat.fromString(requestParams.get(CONFIG_FORMAT));

        switch (configFormat) {
            case HOCON:
                config = ConfigFactory.parseString(new String(requestBody, StandardCharsets.UTF_8));
                break;
            case SQL:
                config = SqlConfigBuilder.of(new String(requestBody, StandardCharsets.UTF_8));
                break;
            case JSON:
            default:
                config = RestUtil.buildConfig(requestHandle(requestBody));
                break;
        }

View on GitHub (pinned to cf67b549a7)

Solutions

1. Add the jobId of the original job to the request parameters (jobId=<originalJobId>) alongside isStartWithSavePoint=true.
2. If you do not know the original jobId, list jobs via the REST job-info endpoint or 'seatunnel.sh -l' to find it before restoring.
3. If you intended a fresh start, remove the isStartWithSavePoint parameter entirely instead of setting it with no jobId.

Example fix

// before
curl -X POST 'http://host:8080/submit-job?jobName=demo&isStartWithSavePoint=true' --data @job.conf
// after
curl -X POST 'http://host:8080/submit-job?jobName=demo&isStartWithSavePoint=true&jobId=861119875632570369' --data @job.conf

if (params.getOrDefault("isStartWithSavePoint", "false") == "true" && !params.containsKey("jobId")) {
  throw new Error("REST savepoint start requires jobId");
}

try { submit(url, params); } catch (IllegalArgumentException e) { if (e.getMessage().contains("jobId when start with save point")) { /* prompt user for original jobId */ } else throw e; }

When it happens

Trigger: POST to the REST job submission endpoint with isStartWithSavePoint=true (or a truthy value) in the request params while omitting the jobId parameter; e.g. curl -X POST .../submit-job -d 'isStartWithSavePoint=true' without '&jobId=<id>'.

Common situations: Developers migrating from CLI-based -s/--savepoint workflows to the HTTP API forget that REST requires the explicit jobId; scripting tools that build the query string dynamically drop empty jobId params; retrying a savepoint restore after the original jobId was lost.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• restoreSourceJobId is required when restoreMode=${restoreMod
• Parameter 'type' cannot be empty.
• --savepoint and --restore-with-checkpoint are mutually exclu
• No checkpoint found for jobId=${jobId}, restoreMode=${restor
• Request body is empty.

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