{"record":{"id":"d73502064925c0a2","repo":"apple/pkl","slug":"unexpected-msgpack-bin-value","errorCode":null,"errorMessage":"Unexpected msgpack bin value","messagePattern":"Unexpected msgpack bin value","errorType":"exception","errorClass":"DecodeException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/util/pklbinary/AbstractPklBinaryDecoder.java","lineNumber":150,"sourceCode":"  private Object doDecode() throws IOException {\n    if (!unpacker.hasNext()) {\n      throw new DecodeException(\"Unexpected EOF\");\n    }\n\n    return switch (unpacker.getNextFormat().getValueType()) {\n      // primitives\n      case NIL -> {\n        unpacker.unpackNil();\n        yield doDecodeNull();\n      }\n      case STRING -> unpacker.unpackString();\n      case INTEGER -> unpacker.unpackLong();\n      case BOOLEAN -> unpacker.unpackBoolean();\n      case FLOAT -> unpacker.unpackDouble();\n      // non-primitive\n      case ARRAY -> decodeNonPrimitive();\n      // things we should never see outside a non-primitive\n      case BINARY -> throw new DecodeException(\"Unexpected msgpack bin value\");\n      case MAP -> throw new DecodeException(\"Unexpected msgpack map value\");\n      case EXTENSION -> throw new DecodeException(\"Unexpected msgpack ext value\");\n    };\n  }\n\n  private Object decodeNonPrimitive() throws IOException {\n    var len = unpacker.unpackArrayHeader();\n    if (len < 1) {\n      throw new DecodeException(\"Unexpected empty object array value\");\n    }\n\n    var codeInt = unpacker.unpackInt();\n    var code = PklBinaryCode.fromInt(codeInt);\n    if (code == null) {\n      throw new DecodeException(\"Unrecognized code 0x%x\", (byte) codeInt);\n    }\n\n    return switch (code) {","sourceCodeStart":132,"sourceCodeEnd":168,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/util/pklbinary/AbstractPklBinaryDecoder.java#L132-L168","documentation":"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.","triggerScenarios":"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.","commonSituations":"Mixing outputs from a generic msgpack serializer with the Pkl binary decoder; hand-assembled msgpack payloads; protocol confusion between two services.","solutions":["Encode the bytes with Pkl's binary encoding (BYTES-coded non-primitive object) instead of a raw msgpack bin value","Verify the payload was produced by Pkl's binary encoder, not another msgpack library","If you need raw bytes, wrap them in a Pkl structure whose code is BYTES before encoding","Check for producer/consumer protocol version mismatches"],"exampleFix":"// before\nbyte[] out = msgpack.write(rawBytes); // top-level bin\n// after\nbyte[] out = pklBinaryEncoder.encodeBytes(rawBytes); // BYTES-coded object","handlingStrategy":"validation","validationCode":"// Producer side: never write raw bin at top level for Pkl binary consumers\n// wrap bytes in a BYTES-coded structure\npacker.packArrayHeader(2);\npacker.packInt(PklBinaryCode.BYTES.toInt());\npacker.packByteArrayHeader(bytes.length);\npacker.writePayload(bytes);","typeGuard":null,"tryCatchPattern":"try {\n  Object v = decoder.decode(bytes);\n} catch (DecodeException e) {\n  if (\"Unexpected msgpack bin value\".equals(e.getMessage())) {\n    // payload was not produced by Pkl's encoder; re-encode at the source\n  } else throw e;\n}","preventionTips":["Only feed Pkl-encoder output to AbstractPklBinaryDecoder","Do not mix generic msgpack serializers with the Pkl binary channel","Wrap byte payloads in BYTES-coded structures","Document the wire format contract between producer and consumer"],"tags":["msgpack","decoding","pkl-binary","malformed-input"],"backgroundTag":"invalid-msgpack-value","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}