alibaba/COLA · error · TransitionFailException

Cannot fire event [${event}] on current state [${sourceState

Error message

Cannot fire event [${event}] on current state [${sourceState}] with context [${context}]

What it means

AlertFailCallback is the default failure callback of the COLA state machine. When fireEvent() is invoked with an event that has no accepted transition from the machine's current state, onFail() throws this StateMachineException with the event, source state, and context. It signals an illegal/undefined event-state combination.

Source

Thrown at cola-components/cola-component-statemachine/src/main/java/com/alibaba/cola/statemachine/builder/AlertFailCallback.java:15

package com.alibaba.cola.statemachine.builder;

import com.alibaba.cola.statemachine.exception.TransitionFailException;

/**
 * Alert fail callback, throw an {@code TransitionFailException}
 *
 * @author 龙也
 * @date 2022/9/15 12:02 PM
 */
public class AlertFailCallback<S, E, C> implements FailCallback<S, E, C> {

    @Override
    public void onFail(S sourceState, E event, C context) {
        throw new TransitionFailException(
            "Cannot fire event [" + event + "] on current state [" + sourceState + "] with context [" + context + "]"
        );
    }
}

View on GitHub (pinned to 352e1a8675)

Solutions

Register a custom FailCallback (via builder) to log/recover instead of throwing
Check current state before firing: only send the event if a transition for (state, event) exists
Add the missing transition in the builder for the (sourceState, event) combination
Catch StateMachineException at the call site and treat it as an invalid business operation

Example fix

// before
stateMachine.fireEvent(currentState, event, context); // throws when event invalid

// after
try {
    stateMachine.fireEvent(currentState, event, context);
} catch (StateMachineException e) {
    log.warn("Illegal event {} for state {}", event, currentState);
}

Defensive patterns

Strategy: try-catch

Validate before calling

// pre-check: ensure a transition exists by catching at fire time is standard,
// but you can validate event ordering in business code before firing
assertAllowedEvent(currentState, event); // app-level whitelist of (state,event) pairs

Try / catch

try {
    stateMachine.fireEvent(sourceState, event, context);
} catch (StateMachineException e) {
    if (e.getMessage().startsWith("Cannot fire event")) {
        // log and reject the business operation as invalid
    } else {
        throw e;
    }
}

Prevention

Maintain a (state,event) whitelist mirroring the machine definition
Set a custom FailCallback for graceful handling
Add all required transitions in the builder
Enforce correct event ordering in business workflow code

When it happens

Trigger: fireEvent(sourceState, event, context) where no transition registered for (sourceState, event), or the transition exists but its condition rejected the context.

Common situations: Sending events in the wrong order (e.g. paying before creating); missing transition definitions in the builder; external inputs triggering events the state machine graph doesn't cover.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

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