apple/pkl · error · DecodeException

Unexpected blank typealias name

Error message

Unexpected blank typealias name

What it means

Thrown by decodeTypeAlias when a TYPEALIAS entry's name string is empty or whitespace-only. Typealias references must be identified by name for the decoder to resolve them, so a blank name is treated as malformed binary input.

Solutions

1. Fix the encoder to emit the non-blank typealias name before the module URI
2. Regenerate the payload with the matching Pkl encoder
3. Confirm the input is a valid, complete Pkl binary file
4. Validate names at the producer before packing

Example fix

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

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

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

When it happens

Trigger: Decoding pkl-binary bytes where a TYPEALIAS code encodes an empty name string; corrupted payloads; an encoder writing fields in the wrong order so the blank URI is read as the name.

Common situations: Hand-written encoders; version mismatch between producer and consumer on the TYPEALIAS entry layout; truncated input.

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 class name
• Unexpected blank object module URI

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

Appendix: source

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

    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();
    if (name.isBlank()) {
      throw new DecodeException("Unexpected blank typealias name");
    }
    var moduleUriString = unpacker.unpackString();
    if (moduleUriString.isBlank()) {
      throw new DecodeException("Unexpected blank typealias module URI");
    }
    var moduleUri = URI.create(moduleUriString);

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

  private Object decodeFunction(int len) throws IOException {
    assertLength(PklBinaryCode.FUNCTION, len, 0);
    currPath.push("'function");
    var result = doDecodeFunction();
    unpacker.skipValue(len - 1);

View on GitHub (pinned to f3efcbfc9b)