apple/pkl · error · DecodeException

Expected structure to have at least slots, found

Error message

Expected %s structure to have at least %d slots, found %d

What it means

DecodeException thrown by assertLength when a msgpack array header declares fewer slots than a Pkl binary structure requires. Every PklBinaryCode-typed structure (object, map, mapping, list, listing, set) encodes a fixed number of leading slots (code, count, members) that must be present. Note the message reports expected+1 as the minimum.

Solutions

1. Regenerate the binary payload with a valid Pkl writer; the array header slot count is wrong
2. Verify the bytes are genuine Pkl binary output, not msgpack from another tool
3. Check producer/consumer Pkl version compatibility for the binary encoding
4. If writing a custom AbstractPklBinaryDecoder subclass, confirm decodeObject/decodeMap/etc. read the correct slot layout

// Producers: ensure every non-primitive array header length covers the fixed prologue slots
// e.g. an OBJECT needs: code + memberCount + members*
assert arrayLen >= minSlotsFor(code);

try {
  Object v = decoder.decode(bytes);
} catch (DecodeException e) {
  if (e.getMessage() != null && e.getMessage().contains("at least")) {
    // treat payload as invalid; re-encode from source
  } else throw e;
}

When it happens

Trigger: A non-primitive array whose header length is less than the minimum required for its PklBinaryCode type; produced when a writer emits a header claiming fewer elements than the type's fixed prologue needs (e.g. a 0- or 1-element array claiming to be an OBJECT).

Common situations: Hand-crafted or corrupted Pkl binary payloads; a producer bug emitting wrong array headers; partial deserialization where only part of an object array was written.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Unexpected empty object array value
• Unexpected msgpack bin value
• Unexpected msgpack ext value
• Unexpected msgpack map value
• Unexpected EOF

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

Appendix: source

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

        return doDecode();
      } catch (MessageInsufficientBufferException e) {
        throw new DecodeException("Unexpected EOF", e);
      }
    } catch (IOException e) {
      throw doIOFail(e);
    } catch (MessagePackException | DecodeException e) {
      var path = new ArrayList<String>(currPath.size());
      for (var iter = currPath.descendingIterator(); iter.hasNext(); ) {
        path.add(iter.next().toString());
      }
      Collections.reverse(path);
      throw doFail(e, unpacker.getTotalReadBytes(), path);
    }
  }

  private void assertLength(PklBinaryCode type, int len, int expected) {
    if (len < expected) {
      throw new DecodeException(
          "Expected %s structure to have at least %d slots, found %d", type, expected + 1, len);
    }
  }

  protected record DecodedObjectMember(PklBinaryCode type, Object key, Object value) {}

  protected abstract RuntimeException doFail(Exception cause, long offset, List<String> path);

  protected abstract RuntimeException doIOFail(IOException cause);

  protected abstract Object doDecodeNull();

  protected abstract Object doDecodeObject(
      String className, URI moduleUri, DecodeIterator<DecodedObjectMember> iter);

  protected abstract Object doDecodeMap(MapDecodeIterator iter);

  protected abstract Object doDecodeMapping(MapDecodeIterator iter);

View on GitHub (pinned to f3efcbfc9b)