apple/pkl · error · DecodeException

Unexpected msgpack bin value

Error message

Unexpected msgpack bin value

What it means

DecodeException thrown by doDecode() when a top-level msgpack value has type BINARY (bin format). In the Pkl binary encoding, raw byte blobs must only appear as members inside a non-primitive structure (e.g. a BYTES-coded object), never as a standalone value. The decoder rejects it because it cannot determine which Pkl type to construct.

Solutions

1. Encode the bytes with Pkl's binary encoding (BYTES-coded non-primitive object) instead of a raw msgpack bin value
2. Verify the payload was produced by Pkl's binary encoder, not another msgpack library
3. If you need raw bytes, wrap them in a Pkl structure whose code is BYTES before encoding
4. Check for producer/consumer protocol version mismatches

Example fix

// before
byte[] out = msgpack.write(rawBytes); // top-level bin
// after
byte[] out = pklBinaryEncoder.encodeBytes(rawBytes); // BYTES-coded object

// Producer side: never write raw bin at top level for Pkl binary consumers
// wrap bytes in a BYTES-coded structure
packer.packArrayHeader(2);
packer.packInt(PklBinaryCode.BYTES.toInt());
packer.packByteArrayHeader(bytes.length);
packer.writePayload(bytes);

try {
  Object v = decoder.decode(bytes);
} catch (DecodeException e) {
  if ("Unexpected msgpack bin value".equals(e.getMessage())) {
    // payload was not produced by Pkl's encoder; re-encode at the source
  } else throw e;
}

When it happens

Trigger: Feeding the decoder plain msgpack output that is a bin value (e.g. someone serialized byte[] directly with a generic msgpack library) instead of Pkl's tagged encoding; a producer bug emitting raw bin at top level.

Common situations: Mixing outputs from a generic msgpack serializer with the Pkl binary decoder; hand-assembled msgpack payloads; protocol confusion between two services.

Related errors

• Expected structure to have at least slots, found
• Unexpected empty object array 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/d73502064925c0a2. Report an issue: GitHub.

Appendix: source

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

  private Object doDecode() throws IOException {
    if (!unpacker.hasNext()) {
      throw new DecodeException("Unexpected EOF");
    }

    return switch (unpacker.getNextFormat().getValueType()) {
      // primitives
      case NIL -> {
        unpacker.unpackNil();
        yield doDecodeNull();
      }
      case STRING -> unpacker.unpackString();
      case INTEGER -> unpacker.unpackLong();
      case BOOLEAN -> unpacker.unpackBoolean();
      case FLOAT -> unpacker.unpackDouble();
      // 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) {

View on GitHub (pinned to f3efcbfc9b)