{"record":{"id":"e8857ec89cf482d2","repo":"apache/hadoop","slug":"read-invalid-opcode-opcode","errorCode":null,"errorMessage":"Read invalid opcode {opCode}","messagePattern":"Read invalid opcode (.+?)","errorType":"exception","errorClass":"java.io.IOException","httpStatus":null,"severity":"error","filePath":"hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSEditLogOp.java","lineNumber":5203,"sourceCode":"\n    LengthPrefixedReader(DataInputStream in, StreamLimiter limiter,\n                         int logVersion) {\n      super(in, limiter, logVersion);\n      this.checksum = DataChecksum.newCrc32();\n    }\n\n    @Override\n    public FSEditLogOp decodeOp() throws IOException {\n      long txid = decodeOpFrame();\n      if (txid == HdfsServerConstants.INVALID_TXID) {\n        return null;\n      }\n      in.reset();\n      in.mark(maxOpSize);\n      FSEditLogOpCodes opCode = FSEditLogOpCodes.fromByte(in.readByte());\n      FSEditLogOp op = cache.get(opCode);\n      if (op == null) {\n        throw new IOException(\"Read invalid opcode \" + opCode);\n      }\n      op.setTransactionId(txid);\n      IOUtils.skipFully(in, 4 + 8); // skip length and txid\n      op.readFields(in, logVersion);\n      // skip over the checksum, which we validated above.\n      IOUtils.skipFully(in, CHECKSUM_LENGTH);\n      return op;\n    }\n\n    @Override\n    public long scanOp() throws IOException {\n      return decodeOpFrame();\n    }\n\n    /**\n     * Decode the opcode \"frame\".  This includes reading the opcode and\n     * transaction ID, and validating the checksum and length.  It does not\n     * include reading the opcode-specific fields.","sourceCodeStart":5185,"sourceCodeEnd":5221,"githubUrl":"https://github.com/apache/hadoop/blob/2add9630210752f88ceb1bb74eb65e37bf41da8e/hadoop-hdfs-project/hadoop-hdfs/src/main/java/org/apache/hadoop/hdfs/server/namenode/FSEditLogOp.java#L5185-L5221","documentation":"LengthPrefixedReader.decodeOp() (modern length+txid+checksum segments) maps the record's first byte to FSEditLogOpCodes and looks it up in the OpInstanceCache; a byte with no known opcode yields no cached op instance and this IOException. In effect: the stream position holds a byte that is not a valid opcode for this binary.","triggerScenarios":"The stream is misaligned after earlier corruption so a body byte is read as an opcode; the file being read is not an edit log; or the segment was written by a newer Hadoop whose opcode values this older binary does not know (downgrade scenario).","commonSituations":"Downgrading NameNode software after newer ops were logged; tools pointed at a random/corrupt file in the current dir; single-byte corruption at a record boundary.","solutions":["If you downgraded, roll forward: restart with the newer release, run a checkpoint (saveNamespace), and only then downgrade again","Run 'hdfs namenode -recover' to skip the unknown record — accepting that this transaction is lost from replay","Confirm the segment's producing version with 'hdfs offlineEditsViewer -i <edits> -o out.xml' run from the release that wrote it","Replace the corrupt segment with a healthy journal copy if available"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"# before any downgrade, confirm no unknown-to-old-binary ops exist\nhdfs offlineEditsViewer -i <newest edits segment> -o /dev/null   # run with the OLDER release","typeGuard":null,"tryCatchPattern":"try {\n  reader.readOp();\n} catch (IOException e) {\n  if (e.getMessage().contains(\"Read invalid opcode\")) {\n    // unknown opcode byte: version skew or corruption\n    // roll forward to the newer release and checkpoint, or recover-skip\n  } else { throw e; }\n}","preventionTips":["Never downgrade a NameNode below the version that wrote the newest edit record; checkpoint first","After upgrades, run saveNamespace to retire version-specific ops early","Point edits-reading tools only at real edit logs in the current directory"],"tags":["hdfs","edit-log","corruption","opcode","downgrade"],"backgroundTag":"unsupported-opcode","analyzedSha":"2add9630210752f88ceb1bb74eb65e37bf41da8e","analyzedAt":"2026-08-22T19:55:07.957Z","schemaVersion":2},"datasetVersion":"2026-08-22T20:17:22.307Z"}