apple/pkl · error

noDescendentPathBetweenModules

noDescendentPathBetweenModules

Error message

noDescendentPathBetweenModules

What it means

Thrown by Module.relativePathTo when the two modules are not related by a descendant path: relativizing the other module's URI against the receiver's URI did not yield a relative (hierarchical) path. This happens when the modules live under unrelated URI schemes or disjoint hierarchies, so no meaningful relative path exists.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/base/ModuleClassNodes.java:57

        CompilerDirectives.transferToInterpreter();
        throw exceptionBuilder().evalError("expectedModuleAsArgument").build();
      }
      var selfKey = VmUtils.getModuleInfo(self).getModuleKey();
      var selfUri = selfKey.getUri();
      var otherKey = VmUtils.getModuleInfo(other).getModuleKey();
      var otherUri = otherKey.getUri();

      var index = selfUri.toString().lastIndexOf('/');
      if (index != -1) {
        var baseUri = URI.create(selfUri.toString().substring(0, index + 1));
        var relativizedUri = baseUri.relativize(otherUri);
        if (!relativizedUri.isAbsolute()) {
          var pathElements = relativizedUri.getPath().split("/");
          return VmList.create(pathElements, pathElements.length - 1);
        }
      }

      throw exceptionBuilder()
          .evalError("noDescendentPathBetweenModules", selfUri, otherUri)
          .build();
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Ensure both modules belong to the same project/hierarchy so a relative path exists
2. Use an absolute URI (otherModule.moduleUri) instead of a relative path when the modules are unrelated
3. Move the target module into the same project directory tree
4. Compute the path manually with URI utilities if you must cross hierarchies

Example fix

// before
module.relativePathTo(externalPackageModule) // unrelated roots
// after
otherModule.moduleUri // use absolute reference instead

function sameHierarchy(a: Module, b: Module): Boolean =
  a.moduleUri.startsWith(commonPrefix) && b.moduleUri.startsWith(commonPrefix)

When it happens

Trigger: Calling selfModule.relativePathTo(otherModule) where otherUri cannot be relativized against selfUri — e.g. one module from a project:/ or package resolver scheme and the other from file:, or from sibling unrelated roots where the relativized URI remains absolute.

Common situations: Comparing modules fetched from different package/project roots, mixing `file:` modules with `project:`/`package:` dependencies, or calling across modules loaded by different resolvers.

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

• cannotHaveRelativeResource
• expectedModuleAsReceiver
• expectedModuleAsArgument
• Failed to convert `pkl.base#String` to `java.net.URI`.
• invalidUri

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