apple/pkl · error · PackageLoadError

invalidUsageOfProjectFromNonFileUri

invalidUsageOfProjectFromNonFileUri

Error message

invalidUsageOfProjectFromNonFileUri

What it means

Project.getTests() maps each test entry to a filesystem Path. If a test entry's URI is not backed by the default filesystem (e.g. it comes from a non-file URI such as a package/jar URI), Path.of throws FileSystemNotFoundException, which is converted to PackageLoadError('invalidUsageOfProjectFromNonFileUri'). The project's tests are only usable when loaded from the local filesystem.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/project/Project.java:473

   *
   * @since 0.32.0
   */
  public PklEvaluatorSettings getResolvedEvaluatorSettings() {
    return resolvedEvaluatorSettings;
  }

  public URI getProjectFileUri() {
    return projectFileUri;
  }

  public List<Path> getTests() {
    return tests.stream()
        .map(
            (it) -> {
              try {
                return Path.of(it);
              } catch (FileSystemNotFoundException e) {
                throw new PackageLoadError("invalidUsageOfProjectFromNonFileUri");
              }
            })
        .collect(Collectors.toList());
  }

  @Override
  public boolean equals(@Nullable Object o) {
    if (this == o) {
      return true;
    }
    if (o == null || getClass() != o.getClass()) {
      return false;
    }
    Project project = (Project) o;
    return Objects.equals(pkg, project.pkg)
        && dependencies.equals(project.dependencies)
        && evaluatorSettings.equals(project.evaluatorSettings)
        && resolvedEvaluatorSettings.equals(project.resolvedEvaluatorSettings)

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Check out / materialize the project on the local filesystem before calling getTests()
2. Verify project.getProjectFileUri().getScheme() equals "file" before invoking getTests()
3. Catch PackageLoadError and fall back to a filesystem-backed copy of the project

Example fix

// before
var tests = project.getTests();
// after
if (!"file".equals(project.getProjectFileUri().getScheme())) {
  throw new IllegalStateException("tests require a filesystem-backed project");
}
var tests = project.getTests();

if (!"file".equals(project.getProjectFileUri().getScheme())) throw new IllegalStateException("getTests requires a filesystem-backed project");

boolean isFileBacked(Project p) { return p.getProjectFileUri().getScheme().equals("file"); }

try { return project.getTests(); } catch (PackageLoadError e) { // materialize project locally and retry }

When it happens

Trigger: Calling project.getTests() on a Project whose URI (and thus its test entries) is not a file: URI — e.g. a project loaded from inside a package or another non-file scheme.

Common situations: Running tests against a project resolved from a remote package instead of a checked-out local copy; embedding Pkl where projects come from virtual filesystems.

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

• cannotEvaluateNonFileBasedTestModule
• ioErrorWritingTestOutputFile
• invalidOutputFileStructure
• ioErrorReadingTestOutputFile
• ioErrorLoadingModule

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