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.

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

• cannotAnalyzeRelativeModuleUri
• cannotGlobUri
• cannotHaveRelativeFragment
• cannotHaveRelativeImport
• cannotHaveRelativeResource

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

Appendix: 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)