alibaba/COLA · error · StateMachineException

${currentStateId} is not found, please check state machine

Error message

${currentStateId} is not found, please check state machine

What it means

StateMachineImpl.getState() resolves a state id to a State object from the machine's stateMap; when the id is absent it dumps the machine structure (showStateMachine) and throws this StateMachineException. It means fireEvent was given a source state that the machine does not define.

Source

Thrown at cola-components/cola-component-statemachine/src/main/java/com/alibaba/cola/statemachine/impl/StateMachineImpl.java:124

        }

        for (Transition<S, E, C> transition : transitions) {
            Transition<S, E, C> transit = null;
            if (transition.getCondition() == null) {
                transit = transition;
            } else if (transition.getCondition().isSatisfied(context)) {
                transit = transition;
            }
            result.add(transit);
        }
        return result;
    }

    private State getState(S currentStateId) {
        State state = StateHelper.getState(stateMap, currentStateId);
        if (state == null) {
            showStateMachine();
            throw new StateMachineException(currentStateId + " is not found, please check state machine");
        }
        return state;
    }

    private void isReady() {
        if (!ready) {
            throw new StateMachineException("State machine is not built yet, can not work");
        }
    }

    @Override
    public String accept(Visitor visitor) {
        StringBuilder sb = new StringBuilder();
        sb.append(visitor.visitOnEntry(this));
        for (State state : stateMap.values()) {
            sb.append(state.accept(visitor));
        }
        sb.append(visitor.visitOnExit(this));

View on GitHub (pinned to 352e1a8675)

Solutions

1. Ensure the state passed to fireEvent is one defined via builder states(); use shared constants for state ids
2. Validate/normalize externally stored state values before firing events
3. Check the printed state machine structure in the exception output to see the valid state ids
4. If state comes from persistence, map legacy ids to current machine state ids

Example fix

// before
sm.fireEvent("STAE_A", event, ctx); // typo -> throws

// after
private static final String STATE_A = "STATE_A";
sm.fireEvent(STATE_A, event, ctx); // defined in builder

// maintain the set of state ids registered in the builder
if (!definedStateIds.contains(currentStateId)) {
    throw new IllegalStateException("unknown state id: " + currentStateId);
}

try {
    sm.fireEvent(stateId, event, ctx);
} catch (StateMachineException e) {
    if (e.getMessage().endsWith("is not found, please check state machine")) {
        // repair or reset externally persisted state to a defined state
    } else {
        throw e;
    }
}

When it happens

Trigger: fireEvent(currentStateId, event, context) with a currentStateId that was never registered in the builder, a misspelled state id, or a stale state reference from an older machine version.

Common situations: Typos in state constants; callers tracking state externally (e.g. DB) with values from a different machine definition; state ids renamed during refactoring.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

• There is no stateMachine instance for ${machineId}, please b
• The state machine with id [${machineId}] is already built, n
• Cannot fire event [${event}] on current state [${sourceState
• ${transition} already Exist, you can not add another one
• State machine is not built yet, can not work

AI-assisted analysis of alibaba/COLA@352e1a8675 (2026-09-08). Data as JSON: /api/errors/0142369e32a4e67d. Report an issue: GitHub.