apache/seatunnel · error · IllegalArgumentException

Unknown TaskGroup State: ${executionState}

Error message

Unknown TaskGroup State: ${executionState}

What it means

PhysicalVertex.stateProcess switches over the task group's ExecutionState; an unrecognized value falls through to this IllegalArgumentException. It indicates the vertex state machine reached a state the processing loop cannot drive, typically an engine inconsistency or an enum value missing from the switch.

Source

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

                                this.taskFullName,
                                ExecutionState.FAILED,
                                errorByPhysicalVertex.get()));
                taskFuture.complete(
                        new TaskExecutionState(
                                taskGroupLocation,
                                ExecutionState.FAILED,
                                errorByPhysicalVertex.get()));
                return;
            case FINISHED:
                stopPhysicalVertex();
                taskFuture.complete(
                        new TaskExecutionState(
                                taskGroupLocation,
                                ExecutionState.FINISHED,
                                errorByPhysicalVertex.get()));
                return;
            default:
                throw new IllegalArgumentException(
                        "Unknown TaskGroup State: " + getExecutionState());
        }
    }

    public void makeTaskGroupFailing(Throwable err) {
        errorByPhysicalVertex.compareAndSet(null, ExceptionUtils.getMessage(err));
        updateTaskState(ExecutionState.FAILING);
    }
}

View on GitHub (pinned to cf67b549a7)

Solutions

1. Align all engine server/worker jar versions and restart the cluster
2. Inspect runningJobStateIMap for the offending TaskGroupLocation's stored state
3. When extending ExecutionState, add matching cases to PhysicalVertex.stateProcess
4. Check task logs to find which updateTaskState call wrote the unexpected state

Example fix

// before
case FAILED:
    handleError();
    break;
// after
case FAILED:
case CANCELED:
    handleError();
    break;

Set<ExecutionState> handled = Set.of(CREATED, SCHEDULED, RUNNING, FINISHED, FAILED, CANCELED, ...);
if (!handled.contains(vertex.getExecutionState())) { log.warn("unhandled state"); }

boolean isHandled(ExecutionState s) { return s != null && HANDLED_STATES.contains(s); }

try { restoreExecutionState(); } catch (IllegalArgumentException e) { if (e.getMessage().startsWith("Unknown TaskGroup State")) { log.error("task group state not handled", e); } else { throw e; } }

When it happens

Trigger: updateTaskState writes an ExecutionState not handled by stateProcess's cases; restoreExecutionState resumes processing while the vertex sits in an uncovered state; new ExecutionState constants added without extending the switch.

Common situations: Engine version mismatch after upgrade introducing new enum values; corrupted runningJobStateIMap entries; custom plugin/task code forcing unusual states.

Related errors

• Unknown Job State: ${jobStatus}
• Unknown Pipeline State: ${pipelineState}
• task group %s not found.
• 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/c91bc1f69987d252. Report an issue: GitHub.