apple/pkl · error · DecodeException

Unexpected blank object class name

Error message

Unexpected blank object class name

What it means

Thrown by decodeObject when decoding a Pkl binary OBJECT code whose class-name string field is empty or whitespace-only. A Pkl object value must identify the class it instantiates, so a blank name means the payload is malformed or corrupt.

Solutions

1. Inspect the binary payload around the object entry and confirm the class name is encoded correctly
2. Re-generate the binary payload with the matching Pkl/encoder version
3. Check that you are not decoding a file of a different format as pkl-binary
4. Reject blank class names at the producer side before emitting the payload

Example fix

// before (encoder side)
packer.packString("");
// after
packer.packString("my.pkg.MyClass");

// producer-side guard before packing
if (className == null || className.isBlank()) throw new IllegalArgumentException("blank class name");

try {
  return decoder.decode(bytes);
} catch (DecodeException e) {
  if (e.getMessage().contains("blank object class name")) {
    throw new MalformedPklBinaryException(e);
  }
  throw e;
}

When it happens

Trigger: Decoding pkl-binary bytes where an OBJECT entry encodes an empty string as the class name; corrupted/truncated payloads; a buggy third-party encoder writing the fields in the wrong order.

Common situations: Manually crafted binary payloads; encoders from incompatible Pkl versions writing fields in a different order; bit-rot or truncation shifting string boundaries.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Expected 3 fields in object member, found
• Unexpected blank class module URI
• Unexpected blank class name
• Unexpected blank object module URI
• Unexpected blank typealias module URI

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

Appendix: source

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

      case BYTES -> decodeBytes(len);
      default -> throw new DecodeException("Unrecognized object code %s", code);
    };
  }

  private void checkCollectionLength(int length, String collectionType) {
    if (length <= collectionSizeLimit) return;
    throw new DecodeException(
        "Unable to decode %s of length %d, exceeded maximum collection size of %d",
        collectionType, length, collectionSizeLimit);
  }

  private Object decodeObject(int len) throws IOException {
    assertLength(PklBinaryCode.OBJECT, len, 3);
    currPath.push("'object");

    var className = unpacker.unpackString();
    if (className.isBlank()) {
      throw new DecodeException("Unexpected blank object class name");
    }
    var classModuleUriString = unpacker.unpackString();
    if (classModuleUriString.isBlank()) {
      throw new DecodeException("Unexpected blank object module URI");
    }
    var classModuleUri = URI.create(classModuleUriString);

    var result =
        doDecodeObject(
            className, classModuleUri, new ObjectDecodeIterator(unpacker.unpackArrayHeader()));
    unpacker.skipValue(len - 4);
    currPath.pop();
    return result;
  }

  private Object decodeMap(int len) throws IOException {
    assertLength(PklBinaryCode.MAP, len, 1);
    currPath.push("'map");

View on GitHub (pinned to f3efcbfc9b)