apple/pkl · error · VmException

externalReaderFailure

externalReaderFailure

Error message

Failed to communicate with external reader process.

What it means

Pkl throws this when glob resolution goes through an external reader process (a custom reader handling a custom scheme) and the process fails or violates the protocol. The original ExternalReaderProcessException is attached as cause. Same family as the externalReaderFailure raised by resource reads.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/expression/unary/ImportGlobNode.java:110

      for (var entry : resolvedElements.entrySet()) {
        builder.addEntry(entry.getKey(), getMemberNode());
      }
      cachedResult = builder.toMapping(resolvedElements);
      return cachedResult;
    } catch (IOException e) {
      throw exceptionBuilder().evalError("ioErrorResolvingGlob", importUri).withCause(e).build();
    } catch (SecurityManagerException | HttpClientException e) {
      throw exceptionBuilder().withCause(e).build();
    } catch (PackageLoadError e) {
      throw exceptionBuilder().adhocEvalError(e.getMessage()).build();
    } catch (InvalidGlobPatternException e) {
      throw exceptionBuilder()
          .evalError("invalidGlobPattern", globPattern)
          .withHint(e.getMessage())
          .build();
    } catch (ExternalReaderProcessException e) {
      throw exceptionBuilder().evalError("externalReaderFailure").withCause(e).build();
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

Inspect the cause chain for the reader's error output and fix the reader implementation.
Ensure the reader command in PklProject is executable, on PATH, and works for glob (listing) requests.
Test the reader standalone against the external reader protocol.
Reinstall or upgrade the tooling/package that provides the reader.

Example fix

// before
externalReader = "my-reader"  // crashes on glob listing
// after
// fix reader to handle list requests, then:
externalReader = "./bin/my-reader"

Defensive patterns

Strategy: retry

Validate before calling

// Before evaluation, smoke-test the external reader process:
//   start it, send a protocol request, assert a well-formed response

Try / catch

try {
  return eval();
} catch (PklException e) {
  if (e.message?.contains("external reader") == true) {
    restartReader(); return retry();  // bounded retries
  }
  throw e;
}

Prevention

Test external readers' glob/listing handling in CI, not only single-resource fetches.
Pin and version the reader binary; verify executability in deployment environments.
Keep reader stdout strictly protocol-conformant; send diagnostics to stderr.

When it happens

Trigger: Evaluating a glob import over a scheme served by an external reader when that process crashes, times out, or returns malformed glob-element listings.

Common situations: Custom project reader with a bug in its glob/element handling; reader binary missing or non-executable in the environment; reader emitting output that does not match the external reader protocol.

Understand the failure class

Background: 'Something went wrong' / 'Request failed (500)' / 'HTTP error! status: 404' — what failed HTTP requests actually mean and how to find the real cause — this error's family across 28 libraries.

Related errors

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