apache/incubator-seata · error · IllegalArgumentException

unknown codec:{code}

Error message

unknown codec:{code}

What it means

Thrown by CompressorType.getByCode(int) when decoding a protocol header whose compression code byte does not match any CompressorType enum (NONE, GZIP, ...). RPC messages carry a compressor code; the receiving side maps it back to an enum and fails on unknown values.

Source

Thrown at core/src/main/java/org/apache/seata/core/compressor/CompressorType.java:79

    private final byte code;

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

    /**
     * Gets result code.
     *
     * @param code the code
     * @return the result code
     */
    public static CompressorType getByCode(int code) {
        for (CompressorType b : CompressorType.values()) {
            if (code == b.code) {
                return b;
            }
        }
        throw new IllegalArgumentException("unknown codec:" + code);
    }

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

    /**

View on GitHub (pinned to e01f97c6db)

Solutions

1. Align seata versions (client, TM, RM, TC server) across the deployment; compression codes are version-dependent.
2. Check transport.compression settings on both ends: disable compression or set it to a codec both sides support.
3. If unexplained, capture the raw payload — a non-Seata client or proxy mangling frames can produce bogus header bytes.

Example fix

# before: mixed versions with compression on
client: seata 2.1 with transport.compression=zstd
server: seata 1.6
# after
both ends: seata 2.x, transport.compression=gzip (or none)

static boolean isKnownCompressorCode(int code) {
    for (CompressorType t : CompressorType.values()) if (t.getCode() == code) return true;
    return false;
}

static Optional<CompressorType> safeByCode(int code) {
    return Arrays.stream(CompressorType.values()).filter(t -> t.getCode() == code).findFirst();
}

catch (IllegalArgumentException e) {
    // unknown wire code => version skew or corruption; drop connection, do not guess a default codec
    channel.close();
    LOG.warn("unsupported compressor code {} from peer; requires version alignment", code);
}

When it happens

Trigger: A peer sends RpcMessage headers with a compressor code outside the known set — typically a newer Seata version that added a codec (e.g. zstd) talking to an older version that lacks it, or corrupted/garbage bytes parsed as a header.

Common situations: Rolling upgrade where client and server run different Seata versions and compression is enabled (transport.compression), a non-Seata service connecting to the TC port, or byte-level protocol corruption from a misbehaving proxy.

Related errors

• Invalid event format: expected prefix '{}', got: {}
• Unknown GlobalStatus[{code}]
• unknown codec:{name}
• Unknown TransactionExceptionCode[{ordinal}]
• Unknown ResultCode[{ordinal}]

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