apple/pkl · error · VmException

invalidUri

invalidUri

Error message

invalidUri

What it means

Thrown when converting the evaluator's baseUri setting into a java.net.URI fails because the value is not a syntactically valid URI. Although Pkl guarantees a file scheme internally, a malformed URI string supplied via EvaluatorSettings triggers this eval error with the offending URI attached.

Solutions

1. Percent-encode spaces and special characters in the path (e.g. 'my%20dir')
2. Use forward slashes and a proper file URI form: file:///C:/path/to/dir
3. Validate the URI with a URI parser before assigning it to baseUri
4. Construct the URI programmatically from a Path instead of hand-writing the string

Example fix

// before
baseUri = "file:///my projects/app"
// after
baseUri = "file:///my%20projects/app"

function isSafeFileUri(u: String): Boolean = u.isRegexMatch(/^file:\/\/\/[^\s<>"\\]+$/, _)

When it happens

Trigger: Setting `baseUri` in EvaluatorSettings to a string that violates URI syntax (illegal characters, unescaped spaces, missing scheme, unbalanced brackets) — e.g. baseUri = "file://C:\\path" or "file:/my dir/".

Common situations: Windows-style paths with backslashes or spaces used unescaped; URIs built by naive string concatenation without percent-encoding; environment-specific config with typos.

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

• Rewrite rule must end with '/', but was
• Rewrite rule must start with 'http://' or 'https://', but…
• Cannot generate documentation for just one module within a…
• Cannot resolve relative URI
• cannotAnalyzeRelativeModuleUri

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/stdlib/evaluatorsettings/EvaluatorSettingsNodes.java:38

import java.net.URI;
import java.net.URISyntaxException;
import org.pkl.core.runtime.VmTyped;
import org.pkl.core.stdlib.ExternalMethod3Node;
import org.pkl.core.util.PathResolver;
import org.pkl.core.util.PathResolvers;

public class EvaluatorSettingsNodes {

  public abstract static class resolvePath extends ExternalMethod3Node {
    @TruffleBoundary
    private URI toUri(String baseUri) {
      try {
        var uri = new URI(baseUri);
        // guaranteed by Pkl
        assert uri.getScheme().equals("file");
        return uri;
      } catch (URISyntaxException e) {
        throw exceptionBuilder().evalError("invalidUri", baseUri).build();
      }
    }

    private PathResolver getPathResolver(boolean forWindows) {
      return forWindows ? PathResolvers.forWindows() : PathResolvers.forPosix();
    }

    @TruffleBoundary
    @Specialization
    protected String eval(VmTyped ignored, String uriStr, String path, boolean forWindows) {
      var uri = toUri(uriStr);
      var baseUri = uri.resolve(".");
      var resolver = getPathResolver(forWindows);
      return resolver.resolvePath(baseUri, path);
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)