apache/incubator-seata · error · IllegalArgumentException

Unknown GlobalStatus[{code}]

Error message

Unknown GlobalStatus[{code}]

What it means

Thrown by GlobalStatus.get(int) when the supplied code is not a valid ordinal into the GlobalStatus enum — negative, larger than the last declared value, or otherwise out of range. It converts a raw protocol/DB integer back into a typed status, so an unrecognized code means the data came from a newer or corrupt source.

Source

Thrown at common/src/main/java/org/apache/seata/core/model/GlobalStatus.java:189

     * @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. Align Seata versions across nodes so all participants know the same GlobalStatus set.
2. Audit the stored/transported code value (log it) and compare with the enum ordinals on this build.
3. Restore or repair corrupted transaction-store rows if the code is garbage.
4. Validate external int input against GlobalStatus.values().length before calling get().

Example fix

// before
GlobalStatus status = GlobalStatus.get(rawCode); // throws for unknown code

// after
GlobalStatus[] all = GlobalStatus.values();
GlobalStatus status = (rawCode >= 0 && rawCode < all.length)
        ? all[rawCode]
        : GlobalStatus.Begin; // or explicit error handling

public static GlobalStatus safeGet(int code) {
    GlobalStatus[] all = GlobalStatus.values();
    return (code >= 0 && code < all.length) ? all[code] : null;
}

boolean isKnownGlobalStatus(int code) {
    return code >= 0 && code < GlobalStatus.values().length;
}

try {
    status = GlobalStatus.get(code);
} catch (IllegalArgumentException e) {
    LOGGER.error("unknown status code {} (version skew or corrupt store)", code);
    status = GlobalStatus.Begin; // quarantine the record instead of crashing
}

When it happens

Trigger: Calling GlobalStatus.get(code) with an integer that does not match any enum ordinal: decoding a session record written by a newer Seata version that added statuses, reading corrupted rows from the global_table/branch_table, or passing an arbitrary int from user code.

Common situations: Version skew: rolling upgrade where an old TC reads statuses written by a new TC; mixed client/server versions; manual SQL edits or data corruption in the transaction store; hand-constructed protocol messages.

Related errors

• Unknown TransactionExceptionCode[{ordinal}]
• Unknown ResultCode[{ordinal}]
• Unknown ClientType[{ordinal}]
• Invalid event format: expected prefix '{}', got: {}
• Unknown TransactionExceptionCode[{ordinal}]

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