apache/incubator-seata · error · IllegalArgumentException

Since fst is no longer maintained, this serialization extens

Error message

Since fst is no longer maintained, this serialization extension has been removed from version 2.0 for security and stability reasons.

What it means

SerializerType.getByCode(int) maps a wire/config codec number back to a SerializerType enum. Since FST serialization was removed in Seata 2.0 (unmaintained, security issues), code 0x0B no longer matches any enum value, so the method detects the legacy FST code and throws IllegalArgumentException explaining the removal. It is a deliberate migration fence, not a generic lookup failure.

Source

Thrown at core/src/main/java/org/apache/seata/core/serializer/SerializerType.java:96

    SerializerType(final byte code) {
        this.code = code;
    }

    /**
     * Gets result code.
     *
     * @param code the code
     * @return the result code
     */
    public static SerializerType getByCode(int code) {
        for (SerializerType b : SerializerType.values()) {
            if (code == b.code) {
                return b;
            }
        }
        if (code == SerializerType.FST.getCode()) {
            throw new IllegalArgumentException(
                    "Since fst is no longer maintained, this serialization extension has been removed from version 2.0 for security and stability reasons.");
        }
        throw new IllegalArgumentException("unknown codec:" + code);
    }

    /**
     * Gets result code.
     *
     * @param name the name
     * @return the result code
     */
    public static SerializerType getByName(String name) {
        for (SerializerType b : SerializerType.values()) {
            if (b.name().equalsIgnoreCase(name)) {
                return b;
            }
        }
        throw new IllegalArgumentException("unknown codec:" + name);

View on GitHub (pinned to e01f97c6db)

Solutions

  1. Upgrade remaining 1.x peers to Seata 2.x so no side advertises FST.
  2. Change serialization config from fst to seata (or another supported codec) on all clients and the server, then restart the whole cluster.
  3. Drain or delete pre-upgrade FST-serialized persistent data (e.g. old undo logs / stored records) before pointing 2.x at it.
  4. If a 1.x client cannot be upgraded, run a matching 1.x server for it instead of forcing mixed versions.

Example fix

# before (file.conf, seata 1.x)
client {
  serialization = "fst"
}

# after (seata 2.x)
client {
  serialization = "seata"
}
Defensive patterns

Strategy: validation

Validate before calling

// before decoding a stored/legacy codec code
int code = readCodecCode();
if (code == 0x0B /* legacy FST code, SerializerType.FST.getCode() in 1.x */) {
    throw new UnsupportedOperationException(
        "FST serialization was removed in Seata 2.0 - re-encode data with 'seata' serialization");
}
SerializerType type = SerializerType.getByCode(code);

Try / catch

try {
    SerializerType t = SerializerType.getByCode(code);
} catch (IllegalArgumentException e) {
    if (e.getMessage().contains("fst")) {
        // data/peer from 1.x: block and require migration, do not retry
        throw new MigrationRequiredException("FST peer/data detected - upgrade to Seata 2.x protocol", e);
    }
    throw e;
}

Prevention

When it happens

Trigger: SerializerType.getByCode(FST code) — decoding an RPC frame or persisted record whose header still carries the FST codec byte (old 1.x peer or old data), or config still specifying fst, while running a 2.x+ build where the FST enum value no longer exists.

Common situations: Rolling upgrade where a 1.x client/server (serialization=fst) talks to a 2.x server; replaying transaction/branch records serialized with FST before the upgrade; configuration left at serialization=fst copied from a 1.x deployment.

Related errors

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