apache/incubator-seata · error · IllegalArgumentException

Cannot convert {name}

Error message

Cannot convert {name}

What it means

Thrown by the compatible io.seata ExecutionStatus.convert when mapping an org.apache.seata ExecutionStatus back to the legacy enum and the target constant is not one of RU/SU/FA/UN/SK. It guards the compatibility bridge between the two enum hierarchies; an unknown constant means the two builds define different status sets.

Source

Thrown at compatible/src/main/java/io/seata/saga/statelang/domain/ExecutionStatus.java:76

    }

    public static ExecutionStatus wrap(org.apache.seata.saga.statelang.domain.ExecutionStatus target) {
        if (target == null) {
            return null;
        }
        switch (target) {
            case RU:
                return RU;
            case SU:
                return SU;
            case FA:
                return FA;
            case UN:
                return UN;
            case SK:
                return SK;
            default:
                throw new IllegalArgumentException("Cannot convert " + target.name());
        }
    }

    public org.apache.seata.saga.statelang.domain.ExecutionStatus unwrap() {
        switch (this) {
            case RU:
                return org.apache.seata.saga.statelang.domain.ExecutionStatus.RU;
            case SU:
                return org.apache.seata.saga.statelang.domain.ExecutionStatus.SU;
            case FA:
                return org.apache.seata.saga.statelang.domain.ExecutionStatus.FA;
            case UN:
                return org.apache.seata.saga.statelang.domain.ExecutionStatus.UN;
            case SK:
                return org.apache.seata.saga.statelang.domain.ExecutionStatus.SK;
            default:
                throw new IllegalArgumentException("Cannot convert " + this.name());
        }

View on GitHub (pinned to e01f97c6db)

Solutions

1. Match versions: use the compatible module built for the same release as the org.apache.seata core.
2. Upgrade the io.seata compatible dependency to a version whose convert() knows the new constant.
3. Avoid mixing namespaces in saga code — stay entirely in org.apache.seata.saga.statelang.domain.

Example fix

<!-- before: mismatched pair -->
<dependency>
  <groupId>org.apache.seata</groupId><artifactId>seata-saga-engine</artifactId><version>2.1.0</version>
</dependency>
<dependency>
  <groupId>io.seata</groupId><artifactId>seata-all-compatible</artifactId><version>1.8.0</version>
</dependency>

<!-- after: aligned release train -->
<dependency>
  <groupId>org.apache.seata</groupId><artifactId>seata-saga-engine</artifactId><version>2.1.0</version>
</dependency>
<dependency>
  <groupId>io.seata</groupId><artifactId>seata-all-compatible</artifactId><version>2.1.0</version>
</dependency>

Set<String> known = Set.of("RU", "SU", "FA", "UN", "SK");
if (!known.contains(target.name())) {
    throw new IllegalStateException(
        "ExecutionStatus." + target.name() + " not convertible by this compatible build; align versions");
}
return ExecutionStatus.convert(target);

boolean isConvertibleExecutionStatus(org.apache.seata.saga.statelang.domain.ExecutionStatus s) {
    return s != null && Set.of("RU", "SU", "FA", "UN", "SK").contains(s.name());
}

try {
    return ExecutionStatus.convert(target);
} catch (IllegalArgumentException e) {
    LOGGER.error("status {} unknown to compatible layer — version skew", target);
    return ExecutionStatus.UN; // fail to 'unknown' rather than crashing the saga engine
}

When it happens

Trigger: Calling ExecutionStatus.convert(target) with an org.apache.seata.saga.statelang.domain.ExecutionStatus constant added in a newer release (or a null/default value not covered by the switch), during saga state-log or API conversion between namespaces.

Common situations: io.seata compatible artifact older than the org.apache.seata core on the classpath after a partial upgrade; new ExecutionStatus constant introduced upstream before the compatible module catches up.

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/e686d6f498661dbd. Report an issue: GitHub.