apple/pkl · error · DecodeException

Unexpected blank class name

Error message

Unexpected blank class name

What it means

Thrown by decodeClass when a CLASS entry's name string is empty or whitespace-only. A class reference in the Pkl binary format must carry the fully qualified class name so the decoder can resolve it; a blank name signals malformed input.

Solutions

1. Fix the encoder to always emit the non-blank class name first
2. Regenerate the payload with the matching Pkl version
3. Verify the input is a complete, untruncated Pkl binary file
4. Add producer-side validation rejecting blank names before packing

Example fix

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

if (name == null || name.isBlank()) throw new IllegalArgumentException("blank class name");

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

When it happens

Trigger: Decoding pkl-binary bytes where a CLASS code encodes an empty name string; corruption shifting string boundaries; a buggy encoder writing fields out of order.

Common situations: Hand-crafted payloads; encoder/decoder version mismatch on the CLASS entry layout; truncated downloads being fed to the decoder.

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 object 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/4dd1cb1e57f9ed39. Report an issue: GitHub.

Appendix: source

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

    return result;
  }

  private Object decodeRegex(int len) throws IOException {
    assertLength(PklBinaryCode.REGEX, len, 1);
    currPath.push("'regex");
    var result = doDecodeRegex(Pattern.compile(unpacker.unpackString()));
    unpacker.skipValue(len - 2);
    currPath.pop();
    return result;
  }

  private Object decodeClass(int len) throws IOException {
    assertLength(PklBinaryCode.CLASS, len, 2);
    currPath.push("'class");

    var name = unpacker.unpackString();
    if (name.isBlank()) {
      throw new DecodeException("Unexpected blank class name");
    }
    var moduleUriString = unpacker.unpackString();
    if (moduleUriString.isBlank()) {
      throw new DecodeException("Unexpected blank class module URI");
    }
    var moduleUri = URI.create(moduleUriString);

    var result = doDecodeClass(name, moduleUri);
    unpacker.skipValue(len - 3);
    currPath.pop();
    return result;
  }

  private Object decodeTypeAlias(int len) throws IOException {
    assertLength(PklBinaryCode.TYPEALIAS, len, 2);
    currPath.push("'typealias");

    var name = unpacker.unpackString();

View on GitHub (pinned to f3efcbfc9b)