apple/pkl · error · DecodeException

Unable to decode of length , exceeded maximum collection…

Error message

Unable to decode %s of length %d, exceeded maximum collection size of %d

What it means

This DecodeException is thrown when a Pkl binary payload declares a collection (list, set, or map) whose declared length exceeds the decoder's configured collectionSizeLimit. The Pkl binary decoder refuses to allocate/iterate collections beyond this safety cap to prevent memory exhaustion from malformed or hostile input.

Solutions

Increase the decoder's collectionSizeLimit to cover the largest collection you legitimately decode
Re-encode the payload with a correct/non-corrupted header (verify the encoder version matches the decoder)
Validate collection sizes in the payload before decoding untrusted input
If the payload is genuinely malformed, regenerate it from the source Pkl module

Example fix

// before
var decoder = new PklBinaryDecoder(bytes); // default collectionSizeLimit
// after
var decoder = new PklBinaryDecoder(bytes, /* collectionSizeLimit */ 1_000_000);

Defensive patterns

Strategy: validation

Validate before calling

long declaredLen = peekCollectionLength(payload); // inspect array/map header
if (declaredLen > MAX_ALLOWED_COLLECTION) {
  throw new IllegalArgumentException("Payload declares collection of " + declaredLen);
}
var value = decoder.decode(payload);

Try / catch

try {
  return decoder.decode(bytes);
} catch (DecodeException e) {
  if (e.getMessage().contains("exceeded maximum collection size")) {
    throw new PayloadLimitException(e);
  }
  throw e;
}

Prevention

Know your decoder's collectionSizeLimit and the max collection your producers emit
Never decode untrusted payloads without a limit check first
Keep encoder and decoder configurations symmetric
Log the collection type/length from the message to size limits appropriately

When it happens

Trigger: Calling a Pkl binary decoder (AbstractPklBinaryDecoder, e.g. via PklObjectDecoder/Evaluator decoding pkl-binary input) on bytes where an array/map header declares a length larger than the decoder's collectionSizeLimit; decoding a payload produced by an encoder with a much larger limit or crafted by hand.

Common situations: Decoding a truncated or hand-edited .pkl binary file where the header length is garbage; decoding an untrusted binary payload; mixing decoder configurations where the producing side allows larger collections than the consuming side.

Understand the failure class

Background: payload too large / request exceeds maximum size: why libraries cap bytes and how to fix oversize payloads — this error's family across 50 libraries.

Parsing and encoding errors: unexpected token, malformed input — why parsers reject input and how to find the real culprit.

Related errors

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

Appendix: source

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

      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");
    }
    var classModuleUriString = unpacker.unpackString();
    if (classModuleUriString.isBlank()) {
      throw new DecodeException("Unexpected blank object module URI");
    }
    var classModuleUri = URI.create(classModuleUriString);

View on GitHub (pinned to f3efcbfc9b)