apple/pkl · error · DecodeException

Unexpected blank typealias module URI

Error message

Unexpected blank typealias module URI

What it means

Thrown by decodeTypeAlias when the TYPEALIAS entry's module URI string is blank. The decoder resolves the typealias via (name, moduleUri); a missing URI makes the reference unresolvable and the payload malformed.

Solutions

1. Ensure the encoder writes the module URI after the name
2. Regenerate the payload with a matching Pkl version
3. Check payload integrity before decoding
4. Reject blank module URIs on the producer side

Example fix

// before
packer.packString(name);
// after
packer.packString(name);
packer.packString(module.getUri().toString());

if (moduleUri == null || moduleUri.isBlank()) throw new IllegalArgumentException("blank typealias module URI");

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

When it happens

Trigger: Decoding pkl-binary bytes where the second string of a TYPEALIAS entry is empty; an encoder skipping the module URI; corruption shifting field boundaries.

Common situations: Third-party encoders omitting the URI; truncated files; decoder/encoder layout mismatch across Pkl versions.

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/bfa597a7d3d03b5c. Report an issue: GitHub.

Appendix: source

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

    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);
    currPath.pop();
    return result;
  }

View on GitHub (pinned to f3efcbfc9b)