apple/pkl · error · ExternalReaderProcessException

externalReaderDoesNotSupportScheme

externalReaderDoesNotSupportScheme

Error message

ErrorMessages.create("externalReaderDoesNotSupportScheme", "resource", scheme)

What it means

This ExternalReaderProcessException is thrown when an external reader process is asked to handle a URI scheme it does not declare support for. ResourceReaders looks up getResourceReaderSpec(scheme) on the external reader process; if the process has no spec for that scheme, no ExternalResolver can be built and the lookup fails. The message names the kind ("resource") and the offending scheme.

Solutions

1. Add the missing scheme to the external reader process's supported `scheme` attribute in its declaration.
2. Correct the scheme typo in either the readerProcess config or the resource URI.
3. Register a built-in/Java ResourceReader for that scheme instead of relying on the external process.

Example fix

// before (pkl script)
readerProcess { scheme = "myproto" }
read("https://example.com/x")
// after
readerProcess { scheme = "myproto" }
read("myproto://example.com/x")

// check declared schemes of readerProcess blocks against URIs used
val declared = setOf("myproto");
val used = uri.substringBefore(":");
require(used in declared || used in builtinSchemes) { "external reader does not support scheme '$used'" }

When it happens

Trigger: Configuring external readers (readerProcess declarations) whose supported scheme list does not include the scheme of a resource being read; the built-in `underlying` resolver is null so the external spec lookup runs and returns null.

Common situations: Reader process registered for e.g. `myproto` but code reads a `file` or `https` resource; typo in the scheme attribute of the readerProcess block; resource scheme changed after adding the external reader.

Understand the failure class

Background: UnsupportedOperationException and "is not supported" errors: when a library deliberately refuses a call — this error's family across 30 libraries.

Related errors

• externalReaderDoesNotSupportScheme
• externalReaderFailure
• externalReaderFailure
• externalReaderFailure
• externalReaderFailure

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/resource/ResourceReaders.java:679

    private final ExternalReaderProcess process;
    private final long evaluatorId;
    private @Nullable ExternalResolver underlying;

    public ExternalProcess(String scheme, ExternalReaderProcess process, long evaluatorId) {
      this.scheme = scheme;
      this.process = process;
      this.evaluatorId = evaluatorId;
    }

    private ExternalResolver getUnderlyingReader()
        throws ExternalReaderProcessException, IOException {
      if (underlying != null) {
        return underlying;
      }

      var spec = process.getResourceReaderSpec(scheme);
      if (spec == null) {
        throw new ExternalReaderProcessException(
            ErrorMessages.create("externalReaderDoesNotSupportScheme", "resource", scheme));
      }
      underlying = new ExternalResolver(spec, process.getResourceResolver(evaluatorId));
      return underlying;
    }

    @Override
    public String getUriScheme() {
      return scheme;
    }

    @Override
    public boolean hasHierarchicalUris() throws ExternalReaderProcessException, IOException {
      return getUnderlyingReader().hasHierarchicalUris();
    }

    @Override
    public boolean isGlobbable() throws ExternalReaderProcessException, IOException {

View on GitHub (pinned to f3efcbfc9b)