alibaba/COLA · error · StateMachineException

State machine is not built yet, can not work

Error message

State machine is not built yet, can not work

What it means

StateMachineImpl tracks a 'ready' flag that is set only after build() completes. isReady(), checked by fireEvent, fireParallelEvent, and verify, throws this StateMachineException when the machine is used before it has been built, preventing operations on an incomplete machine.

Source

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

                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));
        return sb.toString();
    }

    @Override
    public void showStateMachine() {
        SysOutVisitor sysOutVisitor = new SysOutVisitor();
        accept(sysOutVisitor);

View on GitHub (pinned to 352e1a8675)

Solutions

1. Always finish the builder chain with build(machineId) before using the machine
2. Obtain instances via StateMachineFactory.get(machineId), which only returns built machines
3. Fix any exception in the builder chain that leaves the machine unbuilt
4. Ensure initialization completes (synchronously or via a ready check) before consumers fire events

Example fix

// before
StateMachine sm = builder.buildStateMachine(); // chain without proper build finish
sm.fireEvent(...); // throws

// after
StateMachine sm = StateMachineBuilder.builder()
    .states(...).end().build("orderSM"); // ready
sm.fireEvent(...);

// only expose machines obtained from the factory, which enforces built machines
StateMachine sm = StateMachineFactory.get(machineId); // throws early if unbuilt

try {
    sm.fireEvent(...);
} catch (StateMachineException e) {
    if (e.getMessage().contains("not built yet")) {
        sm = finishBuild(machineId); // complete initialization then retry once
    } else {
        throw e;
    }
}

When it happens

Trigger: Calling fireEvent/fireParallelEvent/verify on a state machine instance obtained but whose builder build() has not finished or was never called; using a machine retained from an aborted builder chain.

Common situations: Builder chain interrupted by an exception before build(); asynchronous usage where consumers get a reference to the machine before initialization completes.

Related errors

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

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