{"record":{"id":"e3f33a2a23c58af9","repo":"apache/cassandra","slug":"unknown-opcode-d","errorCode":null,"errorMessage":"Unknown opcode %d","messagePattern":"Unknown opcode (.+?)","errorType":"exception","errorClass":"org.apache.cassandra.transport.ProtocolException","httpStatus":null,"severity":"error","filePath":"src/java/org/apache/cassandra/transport/Message.java","lineNumber":140,"sourceCode":"            for (Type type : Type.values())\n            {\n                if (opcodeIdx[type.opcode] != null)\n                    throw new IllegalStateException(\"Duplicate opcode\");\n                opcodeIdx[type.opcode] = type;\n            }\n        }\n\n        Type(int opcode, Direction direction, Codec<?> codec)\n        {\n            this.opcode = opcode;\n            this.direction = direction;\n            this.codec = codec;\n        }\n\n        public static Type fromOpcode(int opcode, Direction direction)\n        {\n            if (opcode >= opcodeIdx.length)\n                throw new ProtocolException(String.format(\"Unknown opcode %d\", opcode));\n            Type t = opcodeIdx[opcode];\n            if (t == null)\n                throw new ProtocolException(String.format(\"Unknown opcode %d\", opcode));\n            if (t.direction != direction)\n                throw new ProtocolException(String.format(\"Wrong protocol direction (expected %s, got %s) for opcode %d (%s)\",\n                                                          t.direction,\n                                                          direction,\n                                                          opcode,\n                                                          t));\n            return t;\n        }\n\n        @VisibleForTesting\n        public Codec<?> unsafeSetCodec(Codec<?> codec) throws NoSuchFieldException, IllegalAccessException\n        {\n            Codec<?> original = this.codec;\n            Field field = Type.class.getDeclaredField(\"codec\");\n            field.setAccessible(true);","sourceCodeStart":122,"sourceCodeEnd":158,"githubUrl":"https://github.com/apache/cassandra/blob/88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1/src/java/org/apache/cassandra/transport/Message.java#L122-L158","documentation":"Message.Type.fromOpcode maps the frame header's 1-byte opcode to a message type. It throws this ProtocolException when the opcode exceeds the opcode table size or has no registered type, meaning the frame is not a valid native-protocol message. A related error is thrown when the opcode's direction doesn't match (e.g. a REQUEST opcode arriving on a response path).","triggerScenarios":"A frame header contains an opcode not in the protocol's opcode table (e.g. 0x30+), or a null entry in opcodeIdx — from corrupt streams, wrong protocol framing, or garbage bytes after a desync.","commonSituations":"TCP stream desync (a proxy or half-written client misframes messages); fuzzing; a client speaking an incompatible/imagined protocol version; bytes injected mid-stream.","solutions":["Fix client framing so each frame's header (version, flags, opcode, length) matches the actual body; resync the stream if bytes were lost.","Verify client and server support the same protocol version (header version byte must match).","Check for proxies/load balancers corrupting or re-segmenting the CQL stream.","Capture the raw bytes of the offending frame to identify the bad opcode and source."],"exampleFix":"// before: writing opcode as raw arbitrary value\nheader[4] = (byte) 0x7F; // bogus opcode\n// after\nheader[4] = Opcode.QUERY; // use a defined opcode constant (0x07)","handlingStrategy":"try-catch","validationCode":"// validate opcode before writing a frame header\nif (opcode < 0 || opcode >= 0x0E || Opcode.fromOpcode(opcode) == null)\n    throw new IllegalArgumentException(\"Invalid opcode: \" + opcode);","typeGuard":"boolean isKnownOpcode(int op) { return op >= 0 && op < 0x0E; } // valid native protocol opcodes are 0x00-0x0D","tryCatchPattern":"try { connect(); } catch (ProtocolException e) {\n    if (e.getMessage().startsWith(\"Unknown opcode\")) {\n        log.error(\"Frame desync or bogus opcode; reconnect and reset stream\", e);\n    }\n}","preventionTips":["Only use opcode constants from the driver, never raw numbers.","Ensure frame lengths in headers exactly match written body sizes to avoid stream desync.","Keep client and server protocol versions compatible.","Watch for intermediaries (proxies, LBs) corrupting or re-segmenting the TCP stream."],"tags":["protocol","framing","opcode","cql-native-protocol"],"backgroundTag":"invalid-argument-format","analyzedSha":"88fd0f6a0eaed8943f05ac9e8f947882b8ddc8f1","analyzedAt":"2026-09-10T07:29:22.284Z","contentChangedAt":"2026-09-10T07:29:22.284Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}