apple/pkl · error · VmException

invalidResourceUri

invalidResourceUri

Error message

Resource URI `{0}` has invalid syntax.

What it means

Pkl throws this when a resource URI string passed to a `read()` expression cannot be parsed into a valid java.net.URI. The Pkl evaluator catches the URISyntaxException thrown while parsing the resource path and surfaces it as this evaluation error, attaching the parser's reason as a hint.

Source

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

import org.pkl.core.module.ModuleKey;
import org.pkl.core.packages.PackageLoadError;
import org.pkl.core.runtime.VmContext;
import org.pkl.core.util.IoUtils;

public abstract class AbstractReadNode extends UnaryExpressionNode {
  protected final ModuleKey currentModule;

  protected AbstractReadNode(SourceSection sourceSection, ModuleKey currentModule) {
    super(sourceSection);
    this.currentModule = currentModule;
  }

  @TruffleBoundary
  protected final URI parseUri(String resourceUri) {
    try {
      return IoUtils.toUri(resourceUri);
    } catch (URISyntaxException e) {
      throw exceptionBuilder()
          .evalError("invalidResourceUri", resourceUri)
          .withHint(e.getReason())
          .build();
    }
  }

  @TruffleBoundary
  protected final @Nullable Object doRead(String resourceUri, VmContext context, Node readNode) {
    var resolvedUri = resolveResource(currentModule, resourceUri);
    return context.getResourceManager().read(resolvedUri, readNode).orElse(null);
  }

  private URI resolveResource(ModuleKey moduleKey, String resourceUri) {
    var parsedUri = parseUri(resourceUri);
    var context = VmContext.get(this);
    URI resolvedUri;
    try {
      resolvedUri = IoUtils.resolve(context.getSecurityManager(), moduleKey, parsedUri);

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Percent-encode invalid characters in the resource string before passing it to read() (spaces as %20, etc.).
2. Check the error hint for the exact character/position reported by the URI parser and fix that spot.
3. Use a proper URI builder or encode the dynamic portion, e.g. read("https://example.com/" + Uri.encode(path)).
4. For local files, prefer file URIs with forward slashes and no spaces, or rename the file.

Example fix

// before
read("file:/data dir/config.json")
// after
read("file:/data%20dir/config.json")

// Pkl / host-side pre-check that a resource string is URI-safe
fun isUriSafe(s: String): Boolean =
  s.isNotBlank() && !s.any { it.isWhitespace() || it in "{}|\\^`<>\"" } && Regex("^[a-zA-Z][a-zA-Z0-9+.-]*:").containsMatchIn(s)

When it happens

Trigger: Calling `read("...")` with a string that is not syntactically a valid URI, e.g. containing illegal characters like spaces, unencoded braces, or a malformed scheme.

Common situations: Interpolating file paths with spaces or special characters into a resource URI; concatenating a base URL with a path without encoding; typos like `file:/path with space/data.json`.

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
• invalidModuleUri
• 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/e9bacc203a2105c3. Report an issue: GitHub.