apache/incubator-seata · error · IllegalArgumentException

Cannot convert {name}

Error message

Cannot convert {name}

What it means

Thrown by StateType.wrap(org.apache.seata...StateType) when converting an Apache Seata StateType to the io.seata compatibility enum and the default branch is reached. The switch maps all standard types (SERVICE_TASK through LOOP_START); hitting default means the runtime org.apache.seata enum contains a constant the compatible layer predates — a Seata version mismatch or a fork extension.

Source

Thrown at compatible/src/main/java/io/seata/saga/statelang/domain/StateType.java:114

                return SERVICE_TASK;
            case CHOICE:
                return CHOICE;
            case FAIL:
                return FAIL;
            case SUCCEED:
                return SUCCEED;
            case COMPENSATION_TRIGGER:
                return COMPENSATION_TRIGGER;
            case SUB_STATE_MACHINE:
                return SUB_STATE_MACHINE;
            case SUB_MACHINE_COMPENSATION:
                return SUB_MACHINE_COMPENSATION;
            case SCRIPT_TASK:
                return SCRIPT_TASK;
            case LOOP_START:
                return LOOP_START;
            default:
                throw new IllegalArgumentException("Cannot convert " + target.name());
        }
    }

    public org.apache.seata.saga.statelang.domain.StateType unwrap() {
        switch (this) {
            case SERVICE_TASK:
                return org.apache.seata.saga.statelang.domain.StateType.SERVICE_TASK;
            case CHOICE:
                return org.apache.seata.saga.statelang.domain.StateType.CHOICE;
            case FAIL:
                return org.apache.seata.saga.statelang.domain.StateType.FAIL;
            case SUCCEED:
                return org.apache.seata.saga.statelang.domain.StateType.SUCCEED;
            case COMPENSATION_TRIGGER:
                return org.apache.seata.saga.statelang.domain.StateType.COMPENSATION_TRIGGER;
            case SUB_STATE_MACHINE:
                return org.apache.seata.saga.statelang.domain.StateType.SUB_STATE_MACHINE;
            case SUB_MACHINE_COMPENSATION:

View on GitHub (pinned to e01f97c6db)

Solutions

1. Upgrade the io.seata compatibility dependency to the release matching your org.apache.seata core so both StateType enums define the same constants.
2. Stop using the newly introduced state type until all layers understand it, or drop back to the older core version.
3. Enforce a single Seata version via BOM/dependencyManagement to keep the paired jars in lockstep.

Example fix

// before
 <properties>
   <seata.version>2.0.0</seata.version>        <!-- compatible layer -->
   <seata.apache.version>2.2.0</seata.apache.version> <!-- core -->
 </properties>

// after
 <properties>
   <seata.version>2.2.0</seata.version>
   <seata.apache.version>2.2.0</seata.apache.version>
 </properties>

Set<String> known = Arrays.stream(StateType.values())
    .map(StateType::name).collect(Collectors.toSet());

if (target != null && !known.contains(target.name())) {
    throw new IllegalStateException("Apache StateType '" + target
        + "' predates the installed io.seata compatible layer; upgrade it");
}
return StateType.wrap(target);

try {
    return StateType.wrap(target);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("StateType '" + target + "' unmappable; align Seata versions", e);
}

When it happens

Trigger: Calling StateType.wrap(target) — usually indirectly when the compatible adapter reads a state machine parsed by the org.apache.seata engine — with an org.apache.seata StateType constant not covered by the compatible jar (e.g. a new state type introduced in a newer Apache Seata release).

Common situations: Upgrading org.apache.seata core to take advantage of a new state type while the io.seata compatibility (or a third-party SDK built on it) stays on the old release; using a vendor fork with extra state types.

Related errors

• Cannot convert {name}
• Cannot convert {name}
• Cannot convert {name}
• Unknown TransactionExceptionCode[{ordinal}]
• Unknown BranchType[{ordinal}]

AI-assisted analysis of apache/incubator-seata@e01f97c6db (2026-08-14). Data as JSON: /api/errors/33ebec057ea6cff6. Report an issue: GitHub.