apple/pkl · error

e.getMessage()

Error message

e.getMessage()

What it means

AbstractPklBinaryDecoder.decode wraps failures from the MessagePack-based Pkl binary decoding path. When a MessagePackException or DecodeException bubbles out of doDecode(), it is converted (via doFail) into a decoding failure whose message is built from e.getMessage(), annotated with the byte offset (unpacker.getTotalReadBytes()) and the current property path. It signals that the binary (pkl-binary/MensajePack) data does not conform to the expected Pkl object encoding at that offset/path.

Source

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

    this.collectionSizeLimit = collectionSizeLimit;
  }

  protected static class DecodeException extends RuntimeException {
    public DecodeException(String msg, Object... args) {
      super(new Formatter().format(msg, args).toString());
    }
  }

  protected final Object decode() {
    currPath = new ArrayDeque<>();
    try {
      try {
        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) {}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Regenerate the binary module output with the current Pkl version so the encoding matches what the decoder expects.
2. Inspect the reported byte offset and property path to find which field is encoded incorrectly; re-export that value.
3. Verify the input really is Pkl binary format (not plain MessagePack or JSON) and is not truncated or corrupted (check size/checksum against the producer).
4. If you control the writer, fix the code that serializes the offending property so it emits the correct MessagePack type for the schema.

// before decoding: check format markers and size
if (!isPklBinaryFormat(bytes) || bytes.length < MIN_HEADER_SIZE) {
  throw new IllegalArgumentException("Not a valid Pkl binary payload");
}

try {
  return decoder.decode(buffer);
} catch (DecodeException e) {
  // e carries byte offset + property path from doFail
  throw new CorruptionException("Bad Pkl binary data at byte " + e.getOffset() + " path " + e.getPath(), e);
}

When it happens

Trigger: Calling the decoder (decode) on a byte buffer whose contents are not a valid Pkl binary encoding: wrong MessagePack type at a position the schema expects something else, malformed header bytes, or a DecodeException raised by a length/type assertion (e.g. assertLength) inside a container decoder.

Common situations: Consuming a stale or corrupted .pkl.bin artifact cached from an older Pkl version whose binary encoding changed; decoding a file that was truncated or corrupted in transit; pointing the loader at a file that is not Pkl binary format at all (e.g. plain MessagePack or text).

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• Unexpected end of input; 0 message bytes
• object
• string
• Unrecognized member code %s
• Error deserializing `${path.toUri()}`.

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