{"record":{"id":"975f28b95a155f07","repo":"apache/seatunnel","slug":"unknown-pipeline-state-pipelinestate","errorCode":null,"errorMessage":"Unknown Pipeline State: ${pipelineState}","messagePattern":"Unknown Pipeline State: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/dag/physical/SubPlan.java","lineNumber":758,"sourceCode":"                    jobMaster.releasePipelineResource(this);\n                    jobMaster.preApplyResources(this);\n                    restorePipeline();\n                    return;\n                }\n                subPlanDone(state);\n                stopSubPlanStateProcess();\n                pipelineFuture.complete(\n                        new PipelineExecutionState(pipelineId, state, errorByPhysicalVertex.get()));\n                return;\n            case FINISHED:\n                subPlanDone(state);\n                stopSubPlanStateProcess();\n                pipelineFuture.complete(\n                        new PipelineExecutionState(\n                                pipelineId, getPipelineState(), errorByPhysicalVertex.get()));\n                return;\n            default:\n                throw new IllegalArgumentException(\"Unknown Pipeline State: \" + getPipelineState());\n        }\n    }\n\n    public void makePipelineFailing(Throwable e) {\n        errorByPhysicalVertex.compareAndSet(null, ExceptionUtils.getMessage(e));\n        updatePipelineState(PipelineStatus.FAILING);\n    }\n}\n","sourceCodeStart":740,"sourceCodeEnd":767,"githubUrl":"https://github.com/apache/seatunnel/blob/cf67b549a7a6c35fa0beb12d83c62892427ea919/seatunnel-engine/seatunnel-engine-server/src/main/java/org/apache/seatunnel/engine/server/dag/physical/SubPlan.java#L740-L767","documentation":"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.","triggerScenarios":"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.","commonSituations":"Mixed engine versions after upgrade (new enum values); corrupted IMap pipeline state; custom modifications to pipeline scheduling.","solutions":["Run consistent engine versions across master and workers","Inspect the stored pipeline state in runningJobStateIMap for the offending pipeline","Add exhaustive cases to SubPlan.stateProcess when extending PipelineStatus","Review logs to identify which updatePipelineState call produced the unexpected state"],"exampleFix":"// before\ncase RUNNING:\n    scheduleTasks();\n    break;\n// after\ncase RUNNING:\ncase SCHEDULED:\n    scheduleTasks();\n    break;","handlingStrategy":"try-catch","validationCode":"Set<PipelineStatus> handled = Set.of(CREATED, SCHEDULED, RUNNING, FINISHED, FAILED, CANCELED, ...);\nif (!handled.contains(subPlan.getPipelineState())) { log.warn(\"unhandled pipeline state\"); }","typeGuard":"boolean isHandled(PipelineStatus s) { return s != null && HANDLED_PIPELINE_STATES.contains(s); }","tryCatchPattern":"try { startSubPlanStateProcess(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith(\"Unknown Pipeline State\")) { log.error(\"pipeline state not handled\", e); } else { throw e; } }","preventionTips":["Cover all PipelineStatus values in stateProcess","Avoid mixed engine versions","Verify pipeline state in IMap after failover"],"tags":["zeta-engine","pipeline-state","switch-default","state-machine"],"backgroundTag":"unsupported-enum-value","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"}