apple/pkl · error · InvalidGlobPatternException

invalidGlobNonHierarchicalUri

invalidGlobNonHierarchicalUri

Error message

invalidGlobNonHierarchicalUri

What it means

When splitting a glob URI into a base path and wildcard parts, the resolver needs a hierarchical path component. If the URI has no fragment paths and getPath() returns null (typical for opaque, non-hierarchical URIs like mailto: or urn:), it cannot glob and throws invalidGlobNonHierarchicalUri, including the scheme in the message.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/util/GlobResolver.java:452

      }
    }
  }

  /** Split a glob pattern into the base, non-wildcard parts, and the wildcard parts. */
  private static Pair<String, String[]> splitGlobPatternIntoBaseAndWildcards(
      ReaderBase reader, String globPattern, boolean hasAbsoluteGlob)
      throws InvalidGlobPatternException {
    var effectiveGlobPattern = globPattern;
    var basePathSb = new StringBuilder();
    if (hasAbsoluteGlob) {
      var globUri = URI.create(globPattern);
      if (reader.hasFragmentPaths()) {
        effectiveGlobPattern = globUri.getFragment();
        basePathSb.append(IoUtils.stripFragment(globUri)).append('#');
      } else {
        effectiveGlobPattern = globUri.getPath();
        if (effectiveGlobPattern == null) {
          throw new InvalidGlobPatternException(
              ErrorMessages.create("invalidGlobNonHierarchicalUri", globUri.getScheme()));
        }
        basePathSb.append(globUri.getScheme()).append(':');
      }
    }
    var parts = effectiveGlobPattern.split("/");
    int i;

    for (i = 0; i < parts.length; i++) {
      var part = parts[i];
      if (!isRegularPathPart(part)) {
        break;
      }
      basePathSb.append(part).append('/');
    }
    return Pair.of(basePathSb.toString(), Arrays.copyOfRange(parts, i, parts.length));
  }

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Use a hierarchical URI with a path for the glob (e.g. "file:///path/dir/*.pkl", "https://host/path/*.pkl")
2. Fix the URI scheme spelling so it resolves to the intended hierarchical scheme handler
3. If using a custom scheme, ensure the reader supports fragment/paths or provides a path

Example fix

// before
import "myscheme:*.pkl"
// after
import "file:///path/to/project/*.pkl"

function isHierarchicalUri(uri) {
  const u = new java.net.URI(uri); // or parse manually
  return u.getScheme() != null && (u.getPath() != null || u.getFragment() != null);
}

const isGlobbable = (uri) => /^[a-z][a-z0-9+.-]*:/.test(uri) && uri.replace(/^[a-z][a-z0-9+.-]*:/, '').length > 0 && !/^(mailto|urn):/.test(uri);

try {
  var parts = GlobResolver.splitPattern(globUri);
} catch (InvalidGlobPatternException e) {
  if (e.getMessage().contains("NonHierarchicalUri")) throw new IllegalArgumentException("Glob needs a URI with a path: " + globUri);
  throw e;
}

When it happens

Trigger: Calling splitGlobPatternIntoBaseAndWildcards (via GlobResolver.splitPattern / glob resolution entry points) with a glob URI whose scheme defines no path, e.g. "projectpartial:foo" style opaque URIs or a scheme-registered reader without hierarchical paths.

Common situations: Misconfiguring a glob import with a custom/opaque scheme, typos in the URI scheme turning a hierarchical scheme into an unknown one, or using a reader that declares no fragment/path support.

Understand the failure class

Background: "Invalid URL" / "URL cannot be empty": fix the malformed or missing URL behind request-construction failures — this error's family across 50 libraries.

Related errors

• cannotGlobUri
• Failed to convert `pkl.base#String` to `java.net.URI`.
• invalidUri
• invalidUriMissingFragment
• cannotHaveRelativeFragment

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