apple/pkl · error · DecodeException

Unrecognized member code %s

Error message

Unrecognized member code %s

What it means

Defensive branch in AbstractPklBinaryDecoder.getNext: after PklBinaryCode.fromInt() returned a non-null code, the switch over PROPERTY/ELEMENT hit the default case, meaning the code value is a valid PklBinaryCode but not one handled for object members. This indicates an internal encoder/decoder mismatch rather than corrupt data.

Source

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

      }
      DecodedObjectMember member;
      switch (memberCode) {
        case PROPERTY -> {
          var propertyName = unpacker.unpackString();
          currPath.push(propertyName);
          member = new DecodedObjectMember(memberCode, propertyName, doDecode());
        }
        case ENTRY -> {
          var entryKey = doDecode();
          currPath.push(entryKey);
          member = new DecodedObjectMember(memberCode, entryKey, doDecode());
        }
        case ELEMENT -> {
          var elementIndex = unpacker.unpackLong();
          currPath.push(elementIndex);
          member = new DecodedObjectMember(memberCode, elementIndex, doDecode());
        }
        default -> throw new DecodeException("Unrecognized member code %s", memberCode);
      }
      currPath.pop();
      return member;
    }
  }

  protected class CollectionDecodeIterator extends DecodeIterator<Object> {
    CollectionDecodeIterator(int size, String collectionType) {
      super(size);
      checkCollectionLength(size, collectionType);
    }

    @Override
    Object getNext() throws IOException {
      return doDecode();
    }
  }

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Regenerate the payload with a producer matching the decoder's Pkl version
  2. Check the emitted member code against the codes legal for object members (PROPERTY, ELEMENT)
  3. If you control the encoder, ensure only PROPERTY/ELEMENT codes are written for object members
  4. Report a bug to the encoder/decoder maintainers if versions match

Example fix

// before
var code = PklBinaryCode.fromInt(raw);
writeMember(code, value); // may write MAP entries in member position
// after
if (code != PklBinaryCode.PROPERTY && code != PklBinaryCode.ELEMENT) {
  throw new IllegalArgumentException("illegal object member code: " + code);
}
writeMember(code, value);
Defensive patterns

Strategy: try-catch

Validate before calling

int raw = /* member code byte */;
if (raw != PklBinaryCode.PROPERTY_INT && raw != PklBinaryCode.ELEMENT_INT) throw new IllegalStateException("illegal member code " + raw);

Type guard

boolean isMemberCode(PklBinaryCode c) { return c == PklBinaryCode.PROPERTY || c == PklBinaryCode.ELEMENT; }

Try / catch

try { member = decoder.getNext(); } catch (DecodeException e) { throw new UnsupportedPklBinaryVersionException(e); }

Prevention

When it happens

Trigger: Decoding a pkl binary object member whose PklBinaryCode resolves to a code that is not PROPERTY or ELEMENT (e.g. a member-kind code valid elsewhere in the format but not inside an object member), typically from a format-version mismatch or hand-crafted data.

Common situations: Producers written against a different revision of the pkl-binary spec; tests or fuzzers generating member codes that exist in the enum but are not legal in member position.

Related errors

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