apache/dolphinscheduler · error · IllegalArgumentException

Invalid State value: + value

Error message

Invalid State value: + value

What it means

The nested State enum in SerialCommandDto exposes State.of(int) which maps an integer flag value to a State constant; if no constant matches, it throws IllegalArgumentException with the offending value. This guards the deserialization of serialized command state fields against out-of-range or unknown values.

Source

Thrown at dolphinscheduler-dao/src/main/java/org/apache/dolphinscheduler/dao/model/SerialCommandDto.java:115

        // If the workflow instance is finished, then we directly delete the item from the queue
        // so there are no finished state here
        WAITING(0),
        LAUNCHED(1),
        ;
        private final int value;

        State(int value) {
            this.value = value;
        }

        public static State of(int value) {
            for (State state : values()) {
                if (state.value == value) {
                    return state;
                }
            }
            throw new IllegalArgumentException("Invalid State value: " + value);
        }
    }

}

View on GitHub (pinned to 02eac45a1b)

Solutions

1. Log/inspect the offending integer and compare it with the defined State values in SerialCommandDto.
2. Ensure all cluster nodes run the same version so the enum mapping matches.
3. Fix the producer that wrote the invalid state value.
4. If the value is externally supplied, validate it with State.of() inside a try-catch before use.

Example fix

// before
State state = State.of(rawValue); // throws if unknown
// after
State state;
try {
    state = State.of(rawValue);
} catch (IllegalArgumentException e) {
    log.warn("Unknown state {}, defaulting", rawValue);
    state = State.DEFAULT;
}

boolean isValidState(int v) {
    for (State s : State.values()) { if (s.value == v) return true; }
    return false;
}

State tryOf(int v) {
    for (State s : State.values()) { if (s.value == v) return s; }
    return null;
}

try {
    state = State.of(value);
} catch (IllegalArgumentException e) {
    log.warn("Unknown State value {}", value);
    state = fallbackState;
}

When it happens

Trigger: Deserializing a serial-waiting/serial-running command whose encoded state int is not one of the defined State values — e.g. reading corrupted or hand-edited queue/command data, or code built against a different enum version than the data.

Common situations: Upgraded/older DolphinScheduler nodes exchanging serialized commands with different State mappings; manually modified DB rows or queue payloads; bug in the code writing the state int.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• The task execution status code: %s is invalid
• requestType is not a valid value
• contentType is not a valid value
• The execType: {execType} is invalid
• The releaseState {releaseState} is illegal, please check it.

AI-assisted analysis of apache/dolphinscheduler@02eac45a1b (2026-09-06). Data as JSON: /api/errors/bc70172e360ad680. Report an issue: GitHub.