{"record":{"id":"56015da0605ad557","repo":"apple/pkl","slug":"unrecognized-code-0x-x","errorCode":null,"errorMessage":"Unrecognized code 0x%x","messagePattern":"Unrecognized code 0x%x","errorType":"exception","errorClass":"DecodeException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/util/pklbinary/AbstractPklBinaryDecoder.java","lineNumber":165,"sourceCode":"      // non-primitive\n      case ARRAY -> decodeNonPrimitive();\n      // things we should never see outside a non-primitive\n      case BINARY -> throw new DecodeException(\"Unexpected msgpack bin value\");\n      case MAP -> throw new DecodeException(\"Unexpected msgpack map value\");\n      case EXTENSION -> throw new DecodeException(\"Unexpected msgpack ext value\");\n    };\n  }\n\n  private Object decodeNonPrimitive() throws IOException {\n    var len = unpacker.unpackArrayHeader();\n    if (len < 1) {\n      throw new DecodeException(\"Unexpected empty object array value\");\n    }\n\n    var codeInt = unpacker.unpackInt();\n    var code = PklBinaryCode.fromInt(codeInt);\n    if (code == null) {\n      throw new DecodeException(\"Unrecognized code 0x%x\", (byte) codeInt);\n    }\n\n    return switch (code) {\n      case OBJECT -> decodeObject(len);\n      case MAP -> decodeMap(len);\n      case MAPPING -> decodeMapping(len);\n      case LIST -> decodeList(len);\n      case LISTING -> decodeListing(len);\n      case SET -> decodeSet(len);\n      case DURATION -> decodeDuration(len);\n      case DATASIZE -> decodeDataSize(len);\n      case PAIR -> decodePair(len);\n      case INTSEQ -> decodeIntSeq(len);\n      case REGEX -> decodeRegex(len);\n      case CLASS -> decodeClass(len);\n      case TYPEALIAS -> decodeTypeAlias(len);\n      case FUNCTION -> decodeFunction(len);\n      case BYTES -> decodeBytes(len);","sourceCodeStart":147,"sourceCodeEnd":183,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/util/pklbinary/AbstractPklBinaryDecoder.java#L147-L183","documentation":"DecodeException thrown by decodeNonPrimitive() when the first slot of a non-primitive array is an integer that does not map to any known PklBinaryCode. The decoder cannot identify what kind of Pkl value the array represents, so it fails with the unrecognized code in hex.","triggerScenarios":"Payload written by a newer Pkl version whose binary codes the reader does not know; corrupted bytes flipping the code integer; a producer writing raw integers as the code slot instead of valid PklBinaryCode values.","commonSituations":"Pkl version skew (writer newer than reader) when sharing binary module caches across environments; bit-level file corruption; hand-written msgpack fixtures.","solutions":["Align Pkl versions so reader and writer support the same PklBinaryCode set","Inspect the reported hex code and compare with the PklBinaryCode enum for the reader's version","Regenerate the binary payload with a compatible writer","Check for corruption in the stored/transported bytes (checksums help)"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Producer side: validate codes against the reader's PklBinaryCode enum before writing\nif (PklBinaryCode.fromInt(codeInt) == null) {\n  throw new IllegalStateException(\"code 0x\" + Integer.toHexString(codeInt) + \" not known to consumer\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  Object v = decoder.decode(bytes);\n} catch (DecodeException e) {\n  if (e.getMessage() != null && e.getMessage().startsWith(\"Unrecognized code\")) {\n    // version skew or corruption; regenerate payload with matching Pkl versions\n  } else throw e;\n}","preventionTips":["Keep Pkl versions identical across writer and reader environments","Checksum binary artifacts to detect corruption","Avoid writing raw integers as code slots in custom encoders","Add a compatibility test that decodes payloads from the oldest supported producer"],"tags":["msgpack","decoding","pkl-binary","version-mismatch"],"backgroundTag":"invalid-enum-value","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}