apache/incubator-seata · error · IllegalArgumentException

unknown codec:%s

Error message

unknown codec:%s

What it means

The fallback of SerializerType.getByCode(int): the numeric codec id from a message header or config does not equal any SerializerType enum code, and it is not the legacy FST code either, so an IllegalArgumentException 'unknown codec:<code>' is thrown. The number itself is echoed in the message to identify the bad value.

Source

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

    }

    /**
     * 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. Identify the code in the message and check which Seata version defines it; upgrade the peer that produced frames with that codec id.
2. If external probes hit the Seata port, move them to a different port or make them send valid Seata frames.
3. For custom integrations, validate the id against SerializerType values before calling getByCode (see validation below).
4. Capture the offending frame bytes if corruption is suspected (custom proxy, MTU/fragmentation issues).

Example fix

// before
SerializerType type = SerializerType.getByCode(frame.readByte()); // probe/corruption -> unknown codec:72

// after
int code = frame.readByte();
boolean known = Arrays.stream(SerializerType.values()).anyMatch(t -> t.getCode() == code);
if (!known) {
    throw new CorruptedFrameException("unsupported codec id: " + code);
}
SerializerType type = SerializerType.getByCode(code);

int code = frame.readByte();
if (!isKnownCodec(code)) {
    throw new io.netty.handler.codec.CorruptedFrameException("unknown codec id: " + code);
}
SerializerType type = SerializerType.getByCode(code);

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

try {
    SerializerType t = SerializerType.getByCode(code);
} catch (IllegalArgumentException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("unknown codec:")) {
        // corrupt or foreign frame: drop the connection, never retry the same bytes
        ctx.close();
        return;
    }
    throw e;
}

When it happens

Trigger: Decoding an inbound RPC frame whose codec byte is garbage (corrupt/truncated frame, non-Seata traffic hitting the port) or from a peer using a codec id your Seata build does not know; also programmatically calling SerializerType.getByCode with an arbitrary/wrong integer.

Common situations: A load balancer / health checker sending plain HTTP or TCP probes to the Seata service port so the first bytes are parsed as a codec id; version skew where a newer peer uses a newly-added codec id; byte-order/corruption bugs in custom proxies; hand-rolled calls passing config values as ints.

Related errors

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

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