apple/pkl · error · URISyntaxException

invalidUriMissingFragment

invalidUriMissingFragment

Error message

invalidUriMissingFragment

What it means

PackageAssetUri requires package asset URIs to carry a fragment identifying the asset path (e.g. package://host/pkg@1.0.0#/gen/my.pkl). The constructor throws URISyntaxException with message key invalidUriMissingFragment when the URI has no fragment at all, because without it the asset being referenced is undefined.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/packages/PackageAssetUri.java:65

      this.uri = new URI(base.getScheme(), base.getSchemeSpecificPart(), assetPath);
    } catch (URISyntaxException e) {
      // impossible condition, we have a valid URI to start with.
      throw PklBugException.unreachableCode();
    }
    this.packageUri = packageUri;
    this.assetPath = assetPath;
  }

  public PackageAssetUri(String uri) throws URISyntaxException {
    this(new URI(uri));
  }

  public PackageAssetUri(URI uri) throws URISyntaxException {
    this.uri = uri;
    this.packageUri = new PackageUri(uri);
    var fragment = uri.getFragment();
    if (fragment == null) {
      throw new URISyntaxException(
          uri.toString(), ErrorMessages.create("invalidUriMissingFragment", uri));
    }
    if (!fragment.startsWith("/")) {
      throw new URISyntaxException(
          uri.toString(), ErrorMessages.create("cannotHaveRelativeFragment", fragment, uri));
    }
    this.assetPath = fragment;
  }

  public URI getUri() {
    return uri;
  }

  public PackageUri getPackageUri() {
    return packageUri;
  }

  public String getAssetPath() {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Append the asset path fragment to the URI: package://host/pkg@1.0.0#/path/to/file.pkl
2. Check the import/URI string for a missing # character or truncated fragment
3. Verify no intermediate code calls uri.normalize()/strip that removes the fragment before constructing PackageAssetUri

Example fix

// before
new PackageAssetUri(URI.create("package://example.com/pkg@1.0.0"));
// after
new PackageAssetUri(URI.create("package://example.com/pkg@1.0.0#/gen/pkg.pkl"));

boolean hasFragment(URI uri) { return uri.getFragment() != null; }
// run before: new PackageAssetUri(uri)

static PackageAssetUri safeCreate(URI uri) throws URISyntaxException {
  if (uri.getFragment() == null) throw new IllegalArgumentException("package URI needs #/assetPath fragment: " + uri);
  return new PackageAssetUri(uri);
}

try {
  var u = new PackageAssetUri(uri);
} catch (URISyntaxException e) {
  if (e.getReason().contains("fragment")) {
    log.error("Package URI is missing its #/asset fragment: " + e.getInput(), e);
  }
}

When it happens

Trigger: Constructing new PackageAssetUri(URI) with a fragment-less URI such as package://example.com/my/pkg@1.0.0 — e.g. an import string missing the '#/path' part, or a URI stripped of its fragment by earlier processing.

Common situations: Typo in a package import statement (omitting the #/file.pkl part), a tool that URL-normalized the URI and dropped the empty/absent fragment, or copying a package URI without its asset path.

Understand the failure class

Background: "Invalid URL" errors: why new URL(), URI.parse, and reqwest::Url reject your string — missing scheme, whitespace, and bad path format — this error's family across 39 libraries.

Related errors

• Failed to convert `pkl.base#String` to `java.net.URI`.
• invalidUri
• cannotHaveRelativeFragment
• invalidModuleUri
• invalidGlobNonHierarchicalUri

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