apple/pkl · error · DecodeException

Unrecognized object code

Error message

Unrecognized object code %s

What it means

DecodeException thrown by the default branch of decodeNonPrimitive()'s switch: the code is a known PklBinaryCode but not one this decoder handles (e.g. codes reserved or handled only by specialized subclasses). The decoder encountered a structurally valid but unsupported object code.

Solutions

1. Upgrade the Pkl dependency so decodeNonPrimitive handles the reported code
2. Regenerate the payload avoiding the unsupported structure type
3. If maintaining a subclass, add handling (or an explicit error) for the missing code case
4. Check producer/consumer version compatibility for the binary format

// Producer side: restrict emitted PklBinaryCodes to those the consumer's decoder handles
Set<PklBinaryCode> supported = Set.of(OBJECT, MAP, MAPPING, LIST, LISTING, SET, INTSEQ, REGEX, CLASS, TYPEALIAS, BYTES);
if (!supported.contains(code)) {
  throw new IllegalStateException("consumer cannot decode " + code);
}

try {
  Object v = decoder.decode(bytes);
} catch (DecodeException e) {
  if (e.getMessage() != null && e.getMessage().startsWith("Unrecognized object code")) {
    // upgrade consumer or re-produce payload avoiding the unsupported code
  } else throw e;
}

When it happens

Trigger: A PklBinaryCode value that maps in the enum but has no case in decodeNonPrimitive's switch (reserved/extension codes); decoding a payload containing codes intended for a different decoder implementation; version skew where new codes exist in the enum but are unhandled.

Common situations: Mixing decoder implementations across Pkl versions; payloads containing newer structure types decoded by an older consumer; custom decoder subclasses that did not override handling for all codes.

Related errors

• Cannot decode Function value
• Unrecognized code 0x
• Expected structure to have at least slots, found
• Unexpected empty object array value
• Unexpected EOF

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

Appendix: source

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

    }

    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);
      default -> throw new DecodeException("Unrecognized object code %s", code);
    };
  }

  private void checkCollectionLength(int length, String collectionType) {
    if (length <= collectionSizeLimit) return;
    throw new DecodeException(
        "Unable to decode %s of length %d, exceeded maximum collection size of %d",
        collectionType, length, collectionSizeLimit);
  }

  private Object decodeObject(int len) throws IOException {
    assertLength(PklBinaryCode.OBJECT, len, 3);
    currPath.push("'object");

    var className = unpacker.unpackString();
    if (className.isBlank()) {
      throw new DecodeException("Unexpected blank object class name");
    }

View on GitHub (pinned to f3efcbfc9b)