apache/incubator-seata · error · IllegalArgumentException

Unknown GlobalStatus[{code}]

Error message

Unknown GlobalStatus[{code}]

What it means

Compatible-layer (io.seata) mirror of GlobalStatus.get: it indexes the enum by code and throws IllegalArgumentException for out-of-range values. Used when legacy io.seata code converts stored or wire-format status integers into the typed enum.

Source

Thrown at compatible/src/main/java/io/seata/core/model/GlobalStatus.java:172

     * @param code the code
     * @return the global status
     */
    public static GlobalStatus get(byte code) {
        return get((int) code);
    }

    /**
     * Get global status.
     *
     * @param code the code
     * @return the global status
     */
    public static GlobalStatus get(int code) {
        GlobalStatus value = null;
        try {
            value = GlobalStatus.values()[code];
        } catch (Exception e) {
            throw new IllegalArgumentException("Unknown GlobalStatus[" + code + "]");
        }
        return value;
    }

    /**
     * Is one phase timeout boolean.
     *
     * @param status the status
     * @return the boolean
     */
    public static boolean isOnePhaseTimeout(GlobalStatus status) {
        if (status == TimeoutRollbacking
                || status == TimeoutRollbackRetrying
                || status == TimeoutRollbacked
                || status == TimeoutRollbackFailed) {
            return true;
        }
        return false;

View on GitHub (pinned to e01f97c6db)

Solutions

1. Use one consistent Seata version for all compatible and core artifacts.
2. Log the failing code and compare against io.seata GlobalStatus values on both producer and consumer.
3. Migrate fully to org.apache.seata APIs to avoid the double enum conversion.
4. Bounds-check the code before calling get().

Example fix

// before
io.seata.core.model.GlobalStatus s = io.seata.core.model.GlobalStatus.get(code);

// after
io.seata.core.model.GlobalStatus[] all = io.seata.core.model.GlobalStatus.values();
if (code < 0 || code >= all.length) {
    throw new IllegalStateException("status code " + code + " not known by this build; version skew?");
}
io.seata.core.model.GlobalStatus s = all[code];

boolean isKnownGlobalStatus(int code) {
    io.seata.core.model.GlobalStatus[] all = io.seata.core.model.GlobalStatus.values();
    return code >= 0 && code < all.length;
}

try {
    return io.seata.core.model.GlobalStatus.get(code);
} catch (IllegalArgumentException e) {
    LOGGER.error("status code {} unknown to compatible build — version skew", code);
    throw e;
}

When it happens

Trigger: Calling io.seata.core.model.GlobalStatus.get(code) with a negative code or one beyond the last ordinal — during unwrap/conversion of status data produced by a peer running a different Seata version, or with corrupted stored data.

Common situations: io.seata compatible artifacts combined with org.apache.seata components of a different release (added GlobalStatus constants); deserializing old persisted transaction state; garbage ints from malformed messages.

Related errors

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

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