apple/pkl · error · PackageLoadError

cannotResolveInLocalDependencyNotGlobbable

cannotResolveInLocalDependencyNotGlobbable

Error message

cannotResolveInLocalDependencyNotGlobbable

What it means

When a module is imported through a package that is mapped to a local dependency, Pkl resolves the import target on the local filesystem. After resolving, it checks that the resulting module key supports glob (wildcard) imports; if the URI scheme of the local path does not support globbing, this PackageLoadError is thrown during module listing.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/module/ModuleKeys.java:759

      }
      var dep = (Dependency.RemoteDependency) dependency;
      assert dep.getChecksums() != null;
      var bytes = getPackageResolver().getBytes(packageAssetUri, false, dep.getChecksums());
      return ResolvedModuleKeys.virtual(this, uri, new String(bytes, StandardCharsets.UTF_8), true);
    }

    @Override
    public List<PathElement> listElements(SecurityManager securityManager, URI baseUri)
        throws IOException, SecurityManagerException, ExternalReaderProcessException {
      securityManager.checkResolveModule(baseUri);
      var packageAssetUri = PackageAssetUri.create(baseUri);
      var dependency =
          getProjectDependenciesManager().getResolvedDependency(packageAssetUri.getPackageUri());
      var local = getLocalUri(dependency, packageAssetUri);
      if (local != null) {
        var moduleKey = VmContext.get(null).getModuleResolver().resolve(local);
        if (!moduleKey.isGlobbable()) {
          throw new PackageLoadError(
              "cannotResolveInLocalDependencyNotGlobbable", local.getScheme());
        }
        return moduleKey.listElements(securityManager, local);
      }
      var dep = (Dependency.RemoteDependency) dependency;
      assert dep.getChecksums() != null;
      return getPackageResolver().listElements(packageAssetUri, dep.getChecksums());
    }

    @Override
    public boolean hasElement(SecurityManager securityManager, URI elementUri)
        throws IOException, SecurityManagerException, ExternalReaderProcessException {
      securityManager.checkResolveModule(elementUri);
      var packageAssetUri = PackageAssetUri.create(elementUri);
      var dependency =
          getProjectDependenciesManager().getResolvedDependency(packageAssetUri.getPackageUri());
      var local = getLocalUri(dependency, packageAssetUri);
      if (local != null) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

Use a plain `file://` (or platform path) URI for the local dependency so the resolved module key is globbable.
Remove the glob (`**`/`*`) pattern from the import and import concrete module paths instead.
Check the local dependency mapping: the local URI's scheme must support globbing; adjust getLocalUri output or the dependency definition.
If this is a custom ModuleKey implementation, implement isGlobbable() to return true and support listElements.

Example fix

// before (PklProject deps pointing at custom-scheme local path)
dependencies { mypkg { uri = "custom:///libs/mypkg" } }
// after
dependencies { mypkg { uri = "file:///libs/mypkg" } }

Defensive patterns

Strategy: validation

Validate before calling

// before importing with globs from a local dependency, check the local URI scheme
boolean globbable = switch (localUri.getScheme()) {
    case "file", null -> true;  // filesystem-backed schemes support globbing
    default -> false;
};
if (!globbable) throw new IllegalStateException("Scheme " + localUri.getScheme() + " cannot be globbed");

Type guard

boolean isGlobbableLocal(java.net.URI uri) {
  String s = uri.getScheme();
  return s == null || "file".equals(s);
}

Try / catch

try {
  moduleKeys = key.listElements(securityManager, local);
} catch (PackageLoadError e) {
  if (e.getMessage().contains("not globbable")) {
    throw new IllegalArgumentException("Import uses a glob pattern but local dependency scheme is not globbable: " + local, e);
  }
  throw e;
}

Prevention

Keep local dependency URIs on plain filesystem paths (file:// or relative paths).
Avoid glob imports (**) against dependencies; import concrete module paths.
If you write a custom ModuleKey, implement isGlobbable() and listElements() for any scheme you intend to glob.
Test glob imports against each dependency type you support in CI.

When it happens

Trigger: Calling the module-listing path for a package-asset URI where getProjectDependenciesManager().getResolvedDependency() returned a LocalDependency and the resolved local module key (from ModuleResolver.resolve(local)) has isGlobbable() == false, e.g. the local URI scheme cannot expand glob patterns.

Common situations: Using a local path dependency in PklProject.deps.json that points at a file whose scheme (e.g. a custom or non-file scheme) does not support glob imports, then importing modules from it with a glob pattern like `import "pkg://.../**/*.pkl"`.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

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