{"record":{"id":"dcf8279220bdb4bc","repo":"apple/pkl","slug":"unexpected-msgpack-map-value","errorCode":null,"errorMessage":"Unexpected msgpack map value","messagePattern":"Unexpected msgpack map value","errorType":"exception","errorClass":"DecodeException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/util/pklbinary/AbstractPklBinaryDecoder.java","lineNumber":151,"sourceCode":"    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) {\n      case OBJECT -> decodeObject(len);","sourceCodeStart":133,"sourceCodeEnd":169,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/util/pklbinary/AbstractPklBinaryDecoder.java#L133-L169","documentation":"DecodeException thrown by doDecode() when a top-level msgpack value has type MAP. Pkl's binary encoding represents all composite values as ARRAY headers whose first element is a PklBinaryCode; a bare msgpack map at top level is not valid, so decoding aborts.","triggerScenarios":"Decoding output from a generic msgpack serializer that emitted a map at top level; hand-crafted msgpack; producer bug emitting map headers outside a non-primitive wrapper.","commonSituations":"Interoperability mistakes between msgpack tools and Pkl binary data; mixing evaluator message channels; corrupted framing where a map header appears where an array was expected.","solutions":["Ensure the payload uses Pkl binary encoding (arrays tagged with PklBinaryCode), not plain msgpack maps","Re-encode maps via Pkl's MAP-coded non-primitive structure","Confirm you are decoding the correct stream/channel (Pkl binary output, not another msgpack feed)","Check producer and consumer Pkl versions match"],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Producer side: maps must be Pkl MAP-coded arrays, not raw msgpack maps\npacker.packArrayHeader(1 + entries);\npacker.packInt(PklBinaryCode.MAP.toInt());\n// then entries...","typeGuard":null,"tryCatchPattern":"try {\n  Object v = decoder.decode(bytes);\n} catch (DecodeException e) {\n  if (\"Unexpected msgpack map value\".equals(e.getMessage())) {\n    // wrong serializer used upstream; re-encode with Pkl binary encoding\n  } else throw e;\n}","preventionTips":["Use Pkl's binary encoder for all values on this channel","Pin a single serialization library per channel to avoid map-vs-array confusion","Round-trip test encode->decode in CI","Check protocol/channel labels before decoding"],"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"}