apache/seatunnel · error · IllegalArgumentException

Unknown Job State: ${jobStatus}

Error message

Unknown Job State: ${jobStatus}

What it means

PhysicalPlan.stateProcess handles job states with an exhaustive switch; if jobStatus holds a value with no dedicated case, this IllegalArgumentException is thrown. In practice it means the state machine encountered a state the process loop does not know how to handle, indicating an engine-level inconsistency or an enum added without updating the handler.

Source

Thrown at seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/dag/physical/PhysicalPlan.java:418

                updateJobState(JobStatus.RUNNING);
                break;
            case RUNNING:
            case DOING_SAVEPOINT:
                break;
            case FAILING:
            case CANCELING:
                jobMaster.neverNeedRestore();
                getPipelineList().forEach(SubPlan::cancelPipeline);
                break;
            case FAILED:
            case CANCELED:
            case SAVEPOINT_DONE:
            case FINISHED:
                stopJobStateProcess();
                jobEndFuture.complete(new JobResult(jobStatus, errorBySubPlan.get()));
                break;
            default:
                throw new IllegalArgumentException("Unknown Job State: " + jobStatus);
        }
    }

    private void reportJobStateEvent(JobStatus jobStatus) {
        try {
            if (jobStatus.isEndState()
                    || (this.engineConfig != null
                            && this.engineConfig.isReportNonTerminalJobState())) {
                jobMaster
                        .getCoordinatorService()
                        .getEventProcessor()
                        .process(
                                new JobStateEvent(
                                        jobId,
                                        jobImmutableInformation.getJobConfig().getName(),
                                        jobStatus));
            }
        } catch (Exception e) {

View on GitHub (pinned to cf67b549a7)

Solutions

1. Upgrade engine server and clients to matching, latest patch versions
2. Inspect runningJobStateIMap for the offending job and its stored state value
3. Ensure the switch in stateProcess covers every JobStatus constant when extending the engine
4. Report/patch the engine bug if a supported enum value falls through to default

Example fix

// before
case FINISHED:
    stopJobStateProcess();
    break;
// after
case FINISHED:
case CANCELED:
case FAILED:
    stopJobStateProcess();
    break;

// ensure engine jars are consistent
Set<String> statuses = Arrays.stream(JobStatus.values()).map(Enum::name).collect(Collectors.toSet());
if (!statuses.contains(jobStatusName)) throw new IllegalStateException("mismatched engine versions");

boolean knownStatus(JobStatus s) { return s != null && Arrays.asList(JobStatus.values()).contains(s); }

try { startJob(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unknown Job State")) { log.error("engine state corruption/version mismatch", e); } else { throw e; } }

When it happens

Trigger: updateJobState transitions the plan into a state that stateProcess's switch does not cover; startJob kicks off state processing while the plan state is unexpected; a newly added JobStatus constant missing from the switch statement.

Common situations: Running a SeaTunnel version where a new JobStatus enum value was added but internal handling was not fully updated; corrupted IMap state storing an unexpected value; mixing engine server and client JARs of different versions.

Related errors

• Job is trying to leave terminal state ${current}
• Unknown TaskGroup State: ${executionState}
• Unknown Pipeline State: ${pipelineState}
• get job state error
• ${taskFullName} reset state failed, only end state can be re

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