apple/pkl · error · DecodeException

Unrecognized code 0x

Error message

Unrecognized code 0x%x

What it means

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.

Solutions

1. Align Pkl versions so reader and writer support the same PklBinaryCode set
2. Inspect the reported hex code and compare with the PklBinaryCode enum for the reader's version
3. Regenerate the binary payload with a compatible writer
4. Check for corruption in the stored/transported bytes (checksums help)

// Producer side: validate codes against the reader's PklBinaryCode enum before writing
if (PklBinaryCode.fromInt(codeInt) == null) {
  throw new IllegalStateException("code 0x" + Integer.toHexString(codeInt) + " not known to consumer");
}

try {
  Object v = decoder.decode(bytes);
} catch (DecodeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unrecognized code")) {
    // version skew or corruption; regenerate payload with matching Pkl versions
  } else throw e;
}

When it happens

Trigger: 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.

Common situations: Pkl version skew (writer newer than reader) when sharing binary module caches across environments; bit-level file corruption; hand-written msgpack fixtures.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Expected structure to have at least slots, found
• Unexpected empty object array value
• Unexpected EOF
• Unexpected msgpack bin value
• Unexpected msgpack ext value

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/56015da0605ad557. Report an issue: GitHub.

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/util/pklbinary/AbstractPklBinaryDecoder.java:165

      // non-primitive
      case ARRAY -> decodeNonPrimitive();
      // things we should never see outside a non-primitive
      case BINARY -> throw new DecodeException("Unexpected msgpack bin value");
      case MAP -> throw new DecodeException("Unexpected msgpack map value");
      case EXTENSION -> throw new DecodeException("Unexpected msgpack ext value");
    };
  }

  private Object decodeNonPrimitive() throws IOException {
    var len = unpacker.unpackArrayHeader();
    if (len < 1) {
      throw new DecodeException("Unexpected empty object array value");
    }

    var codeInt = unpacker.unpackInt();
    var code = PklBinaryCode.fromInt(codeInt);
    if (code == null) {
      throw new DecodeException("Unrecognized code 0x%x", (byte) codeInt);
    }

    return switch (code) {
      case OBJECT -> decodeObject(len);
      case MAP -> decodeMap(len);
      case MAPPING -> decodeMapping(len);
      case LIST -> decodeList(len);
      case LISTING -> decodeListing(len);
      case SET -> decodeSet(len);
      case DURATION -> decodeDuration(len);
      case DATASIZE -> decodeDataSize(len);
      case PAIR -> decodePair(len);
      case INTSEQ -> decodeIntSeq(len);
      case REGEX -> decodeRegex(len);
      case CLASS -> decodeClass(len);
      case TYPEALIAS -> decodeTypeAlias(len);
      case FUNCTION -> decodeFunction(len);
      case BYTES -> decodeBytes(len);

View on GitHub (pinned to f3efcbfc9b)