apache/incubator-seata · error · IllegalArgumentException

Unknown magic code: {b0}, {b1}

Error message

Unknown magic code: {b0}, {b1}

What it means

IllegalArgumentException from MultiProtocolDecoder.decideVersion: the first two bytes of an inbound frame do not equal Seata's magic code bytes. The magic code is a fixed frame signature; a mismatch means the bytes arriving on this port are not a Seata RPC frame at all (or are corrupted/encrypted/rewritten in transit).

Source

Thrown at core/src/main/java/org/apache/seata/core/rpc/netty/MultiProtocolDecoder.java:174

                    }
                    ctx.pipeline().remove(this);
                }
            }
        } catch (Exception exx) {
            LOGGER.error("Decode frame error, cause: {}", exx.getMessage());
            throw new DecodeException(exx);
        }
        return decoded;
    }

    protected byte decideVersion(Object in) {
        if (in instanceof ByteBuf) {
            ByteBuf frame = (ByteBuf) in;
            frame.markReaderIndex();
            byte b0 = frame.readByte();
            byte b1 = frame.readByte();
            if (ProtocolConstants.MAGIC_CODE_BYTES[0] != b0 || ProtocolConstants.MAGIC_CODE_BYTES[1] != b1) {
                throw new IllegalArgumentException("Unknown magic code: " + b0 + ", " + b1);
            }

            byte version = frame.readByte();
            frame.resetReaderIndex();
            return version;
        }
        return -1;
    }

    protected boolean isV0(ByteBuf in) {
        boolean isV0 = false;
        in.markReaderIndex();
        byte b0 = in.readByte();
        byte b1 = in.readByte();
        // v1/v2/v3 : b2 = version
        // v0 : 1st byte in FLAG(2byte:0x10/0x20/0x40/0x80)
        byte b2 = in.readByte();
        if (ProtocolConstants.MAGIC_CODE_BYTES[0] == b0 && ProtocolConstants.MAGIC_CODE_BYTES[1] == b1 && 0 == b2) {

View on GitHub (pinned to e01f97c6db)

Solutions

1. Check what is connecting: find the source of the frames (probe config, scanner, wrong client address)
2. Point health probes at the seata console/http port, not the RPC listen port
3. Ensure TLS/SSL settings match on both ends (both plaintext or both TLS)
4. Verify the registry advertises the correct RPC port of the seata-server

Example fix

# before: k8s probe hits the RPC port
livenessProbe:
  tcpSocket: { port: 8091 }  # seata RPC port

# after: probe the console port
livenessProbe:
  httpGet: { path: /, port: 7091 }

// sanity: ensure the configured endpoint is a seata RPC endpoint before connect
// e.g. verify registry advertises the seata-server netty port (default 8091), not console 7091

catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Unknown magic code")) {
        // wrong endpoint/protocol: stop pointing non-seata traffic at this port
    }
}

When it happens

Trigger: Any non-Seata traffic reaching the seata server/client port (HTTP health checks, monitoring probes, port scanners, another protocol); TLS enabled on one side only so ciphertext is parsed as plaintext; a proxy or LB that mangles the stream.

Common situations: Kubernetes readiness/liveness probes pointed at the transaction port instead of the console port; aLoadBalancer TCP health check sending an HTTP HEAD; SSL misconfiguration; pointing the client at the wrong service/port in the registry.

Related errors

• Unsupported version: {version}
• Invalid event format: expected prefix '{}', got: {}
• {dataName} data is too large, size={length}
• Unknown GlobalStatus[{code}]
• unknown codec:{code}

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