apache/seatunnel · error · IllegalArgumentException

Unknown Pipeline State: ${pipelineState}

Error message

Unknown Pipeline State: ${pipelineState}

What it means

SubPlan.stateProcess switches over PipelineStatus to drive pipeline lifecycle; an unhandled value reaches this IllegalArgumentException default. It signals the pipeline state machine encountered a state the processing loop cannot handle — usually an engine bug, enum drift, or corrupted state.

Source

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

                    jobMaster.releasePipelineResource(this);
                    jobMaster.preApplyResources(this);
                    restorePipeline();
                    return;
                }
                subPlanDone(state);
                stopSubPlanStateProcess();
                pipelineFuture.complete(
                        new PipelineExecutionState(pipelineId, state, errorByPhysicalVertex.get()));
                return;
            case FINISHED:
                subPlanDone(state);
                stopSubPlanStateProcess();
                pipelineFuture.complete(
                        new PipelineExecutionState(
                                pipelineId, getPipelineState(), errorByPhysicalVertex.get()));
                return;
            default:
                throw new IllegalArgumentException("Unknown Pipeline State: " + getPipelineState());
        }
    }

    public void makePipelineFailing(Throwable e) {
        errorByPhysicalVertex.compareAndSet(null, ExceptionUtils.getMessage(e));
        updatePipelineState(PipelineStatus.FAILING);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Run consistent engine versions across master and workers
2. Inspect the stored pipeline state in runningJobStateIMap for the offending pipeline
3. Add exhaustive cases to SubPlan.stateProcess when extending PipelineStatus
4. Review logs to identify which updatePipelineState call produced the unexpected state

Example fix

// before
case RUNNING:
    scheduleTasks();
    break;
// after
case RUNNING:
case SCHEDULED:
    scheduleTasks();
    break;

Set<PipelineStatus> handled = Set.of(CREATED, SCHEDULED, RUNNING, FINISHED, FAILED, CANCELED, ...);
if (!handled.contains(subPlan.getPipelineState())) { log.warn("unhandled pipeline state"); }

boolean isHandled(PipelineStatus s) { return s != null && HANDLED_PIPELINE_STATES.contains(s); }

try { startSubPlanStateProcess(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unknown Pipeline State")) { log.error("pipeline state not handled", e); } else { throw e; } }

When it happens

Trigger: updatePipelineState writes a PipelineStatus with no matching case in stateProcess; startSubPlanStateProcess begins processing while the pipeline is in an uncovered state; new PipelineStatus values added without updating the switch.

Common situations: Mixed engine versions after upgrade (new enum values); corrupted IMap pipeline state; custom modifications to pipeline scheduling.

Related errors

• Unknown Job State: ${jobStatus}
• Unknown TaskGroup State: ${executionState}
• ${pipelineFullName} reset state failed, only end state can b
• Job is trying to leave terminal state ${current}
• ${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/975f28b95a155f07. Report an issue: GitHub.