apache/incubator-seata · error · IllegalArgumentException

Cannot convert {name}

Error message

Cannot convert {name}

What it means

Thrown by RecoverStrategy.wrap(org.apache.seata...RecoverStrategy) when converting an Apache Seata RecoverStrategy back to the io.seata compatibility enum and the value falls into the default branch. Only Compensate and Forward exist and both are handled, so the throw signals that the incoming enum class has constants the compatible layer does not know about — i.e. the two artifacts were built from different Seata generations.

Source

Thrown at compatible/src/main/java/io/seata/saga/statelang/domain/RecoverStrategy.java:45

     */
    Compensate,

    /**
     * Forward
     */
    Forward;

    public static RecoverStrategy wrap(org.apache.seata.saga.statelang.domain.RecoverStrategy target) {
        if (target == null) {
            return null;
        }
        switch (target) {
            case Compensate:
                return Compensate;
            case Forward:
                return Forward;
            default:
                throw new IllegalArgumentException("Cannot convert " + target.name());
        }
    }

    public org.apache.seata.saga.statelang.domain.RecoverStrategy unwrap() {
        switch (this) {
            case Compensate:
                return org.apache.seata.saga.statelang.domain.RecoverStrategy.Compensate;
            case Forward:
                return org.apache.seata.saga.statelang.domain.RecoverStrategy.Forward;
            default:
                throw new IllegalArgumentException("Cannot convert " + this.name());
        }
    }
}

View on GitHub (pinned to e01f97c6db)

Solutions

1. Pin all Seata artifacts (io.seata legacy and/or org.apache.seata) to one consistent release using dependencyManagement / a BOM / Gradle platform.
2. Exclude the stale transitive saga artifact (e.g. io.seata:seata-saga-statelang) brought in by an older third-party starter.
3. Add an enforcer rule (requireUpperBoundDeps or dependencyConvergence) so mismatched Seata versions fail the build instead of failing at runtime.

Example fix

// before
 RecoverStrategy wrapped = RecoverStrategy.wrap(apacheStrategy); // throws on skewed jars

// after: align versions, then guard the boundary
 if (apacheStrategy == null
         || apacheStrategy.name() == null
         || !Arrays.asList("Compensate", "Forward").contains(apacheStrategy.name())) {
     throw new IllegalStateException("Unsupported RecoverStrategy: " + apacheStrategy);
 }
 RecoverStrategy wrapped = RecoverStrategy.wrap(apacheStrategy);

private static final Set<String> MAPPABLE = Set.of("Compensate", "Forward");

public static RecoverStrategy safeWrap(org.apache.seata.saga.statelang.domain.RecoverStrategy target) {
    if (target != null && !MAPPABLE.contains(target.name())) {
        throw new IllegalStateException("Unsupported RecoverStrategy: " + target
            + " — mixed io.seata/org.apache.seata versions on classpath");
    }
    return RecoverStrategy.wrap(target);
}

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

When it happens

Trigger: Calling RecoverStrategy.wrap(target) where target is an org.apache.seata.saga.statelang.domain.RecoverStrategy constant not present in the switch — only possible when the runtime org.apache.seata jar defines more constants than the compatible io.seata jar was compiled against (version skew), or via a custom-built/hacked enum.

Common situations: Mixed io.seata + org.apache.seata jars on one classpath during incremental migration to Apache Seata 2.x; a saga engine module left on an older release while the app core was upgraded; dependency convergence not enforced in a multi-module build.

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