apple/pkl · error · VmException

cannotHaveRelativeResource

cannotHaveRelativeResource

Error message

Module `{0}` cannot have a relative resource URI.

What it means

Pkl throws this after resolution when the resolved resource URI is not absolute. Resource URIs must resolve to absolute URIs; a relative result means the module's own key cannot serve as a proper resolution base. The module's URI is reported in the message.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/expression/unary/AbstractReadNode.java:84

      throw exceptionBuilder().evalError("cannotFindResource", resourceUri).build();
    } catch (URISyntaxException e) {
      throw exceptionBuilder()
          .evalError("invalidResourceUri", resourceUri)
          .withHint(e.getReason())
          .build();
    } catch (IOException e) {
      throw exceptionBuilder()
          .evalError("ioErrorReadingResource", resourceUri)
          .withHint(e.getMessage())
          .build();
    } catch (PackageLoadError | SecurityManagerException e) {
      throw exceptionBuilder().withCause(e).build();
    } catch (ExternalReaderProcessException e) {
      throw exceptionBuilder().evalError("externalReaderFailure").withCause(e).build();
    }

    if (!resolvedUri.isAbsolute()) {
      throw exceptionBuilder().evalError("cannotHaveRelativeResource", moduleKey.getUri()).build();
    }
    return resolvedUri;
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Use an absolute resource URI (with scheme) in the read() call.
2. Load the module through a proper resolvable source (file path or URL) so its module key is absolute.
3. Fix how the module is evaluated programmatically — pass a resolved ModuleSource/URI rather than raw text.
4. Check the reported module URI to see why the base cannot produce an absolute result.

Example fix

// before
read("config.json")  // module has no absolute base
// after
read("file:///path/to/project/config.json")

// Host side: ensure modules are loaded from resolvable sources
// ModuleSource path/url must be absolute: Path.of(p).toAbsolutePath() / new URI(...).resolve(...)  != null && uri.isAbsolute()

When it happens

Trigger: Calling `read()` from a module whose key is a relative or scheme-less URI, with a relative resource URI that does not become absolute after resolution.

Common situations: Evaluating modules via REPL or API with synthetic/non-standard module keys; reading resources from a module that was loaded as raw text with no proper base URI.

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

• invalidResourceUri
• noDescendentPathBetweenModules
• Failed to convert `pkl.base#String` to `java.net.URI`.
• invalidUri
• invalidUriMissingFragment

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