apple/pkl · error · VmException

externalReaderFailure

externalReaderFailure

Error message

externalReaderFailure

What it means

If a module URI is handled by an external reader (a user-registered external reader process, e.g. via pkl release external readers or custom `externalReader` wiring) and that process fails, ModuleResolver turns the ExternalReaderProcessException into the eval error 'externalReaderFailure' with the underlying exception as cause.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/runtime/ModuleResolver.java:88

      throw new VmExceptionBuilder()
          .withOptionalLocation(importNode)
          .bug("Cannot resolve relative URI `%s`.", moduleUri)
          .build();
    }

    var normalized = moduleUri.normalize();
    for (var factory : factories) {
      Optional<ModuleKey> key;
      try {
        key = factory.create(normalized);
      } catch (URISyntaxException e) {
        throw new VmExceptionBuilder()
            .withOptionalLocation(importNode)
            .evalError("invalidModuleUri", moduleUri)
            .withHint(e.getReason())
            .build();
      } catch (ExternalReaderProcessException e) {
        throw new VmExceptionBuilder()
            .withOptionalLocation(importNode)
            .evalError("externalReaderFailure")
            .withCause(e)
            .build();
      } catch (IOException e) {
        throw new VmExceptionBuilder()
            .withOptionalLocation(importNode)
            .evalError("ioErrorLoadingModule")
            .withCause(e)
            .build();
      }
      if (key.isPresent()) return key.get();
    }

    throw new VmExceptionBuilder()
        .evalError("noModuleLoaderRegistered", moduleUri)
        .withOptionalLocation(importNode)
        .build();

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Inspect the cause attached to the error for the external reader's stderr/exit status.
  2. Verify the external reader command works standalone when invoked with the same URI.
  3. Fix the reader registration (path/command) in your CLI config or project settings; update the reader to match your Pkl version.
Defensive patterns

Strategy: try-catch

Validate before calling

// smoke-test the external reader: run its command with a known URI and check exit code 0 before evaluation.

Try / catch

catch (VmException e) { if ("externalReaderFailure".equals(e.getCode())) { log(e.getCause()); /* fall back to a local module or abort */ } }

Prevention

When it happens

Trigger: resolve() encounters a URI whose scheme is claimed by an external reader and factory.create() throws ExternalReaderProcessException — the external reader process crashed, exited non-zero, or produced invalid output.

Common situations: Custom external reader binaries not on PATH, crashing on the requested module, misconfigured reader command, or reader incompatible with the Pkl CLI version.

Related errors

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