apple/pkl · error

cannotFindResource

cannotFindResource

Error message

cannotFindResource

What it means

Thrown by the `read()` builtin when no reader can produce content for the given URI string — the resource does not exist or is not accessible. This is Pkl's equivalent of file-not-found for the read API, and the requested URI is included in the error.

Solutions

1. Verify the URI string is correct and the file/resource actually exists at evaluation time.
2. For relative paths, resolve them against the module's location — check the current module directory.
3. For `env:` reads, ensure the environment variable is exported in the evaluation environment.
4. Add the file's directory to the module path if it is outside the current tree.
5. Use `read().exists`/catch semantics or provide a default via null-safe access when absence is expected.

Example fix

// before
val cfg = read("config.pkl").text
// after
val cfg = if (read?("config.pkl") != null) read("config.pkl").text else ""

function safeRead(uri) =
  if (uri.startsWith("env:")) {
    val name = uri.substring(4)
    if (System.getenv(name) == null) throw new Error("env var not set: " + name)
  }
  uri

const resourceLikelyExists = (uri) => uri.startsWith('env:') ? process.env[uri.slice(4)] != null : fs.existsSync(resolve(uri))

try {
  content = read(uri).text
} catch (e) {
  if (e.code === 'cannotFindResource') content = defaultContent(e.data.resourceUri)
  else throw e
}

When it happens

Trigger: Calling `read("file.txt")`, `read("env:VAR")`, or `read("prop:x")` where the resource manager resolves nothing: nonexistent file, unset environment variable, undefined property, wrong URI scheme.

Common situations: Typos in file paths, reading files outside the module path, missing environment variables in CI, referencing resources deleted or renamed after authoring the module.

Understand the failure class

Background: 'Could not be found', 'does not exist', 'not found in database': the resource-not-found family when an ID, slug, key, or URI lookup comes back empty — this error's family across 20 libraries.

Related errors

• cannotFindResource
• cannotFindResource
• Cannot find Pkl module
• cannotFindCertFile
• cannotHaveRelativeResource

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/expression/unary/ReadNode.java:37

import com.oracle.truffle.api.dsl.Specialization;
import com.oracle.truffle.api.nodes.NodeInfo;
import com.oracle.truffle.api.source.SourceSection;
import org.pkl.core.module.ModuleKey;
import org.pkl.core.runtime.VmContext;

@NodeInfo(shortName = "read")
public abstract class ReadNode extends AbstractReadNode {
  protected ReadNode(SourceSection sourceSection, ModuleKey moduleKey) {
    super(sourceSection, moduleKey);
  }

  @Specialization
  public Object read(String resourceUri) {
    var result = doRead(resourceUri, VmContext.get(this), this);
    if (result != null) return result;

    CompilerDirectives.transferToInterpreter();
    throw exceptionBuilder().evalError("cannotFindResource", resourceUri).build();
  }
}

View on GitHub (pinned to f3efcbfc9b)