apple/pkl · error

externalReaderFailure

externalReaderFailure

Error message

externalReaderFailure

What it means

Glob imports whose scheme is served by an external reader (a registered external filesystem reader process) fail with `externalReaderFailure` when the external reader process itself errors — CommandSpecParser catches ExternalReaderProcessException raised while resolving the glob and rethrows it as an eval error with the exception as cause.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java:1206

    try {
      if (!globModuleKey.isGlobbable()) {
        throw exceptionBuilder()
            .evalError("cannotGlobUri", importUri, importUri.getScheme())
            .build();
      }
      var resolvedElements =
          GlobResolver.resolveGlob(securityManager, globModuleKey, null, null, uriString);

      var builder = new VmObjectBuilder(resolvedElements.size());
      for (var entry : resolvedElements.entrySet()) {
        var moduleKey = moduleResolver.resolve(entry.getValue().uri());
        builder.addEntry(entry.getKey(), language.loadModule(moduleKey));
      }
      return builder.toMapping(resolvedElements);
    } catch (IOException e) {
      throw exceptionBuilder().evalError("ioErrorResolvingGlob", importUri).withCause(e).build();
    } catch (ExternalReaderProcessException e) {
      throw exceptionBuilder().evalError("externalReaderFailure").withCause(e).build();
    } catch (SecurityManagerException e) {
      throw exceptionBuilder().withCause(e).build();
    } catch (InvalidGlobPatternException e) {
      throw exceptionBuilder()
          .evalError("invalidGlobPattern", uriString)
          .withHint(e.getMessage())
          .build();
    }
  }

  // endregion
  // region utilities

  private static @Nullable String exportNullableString(VmObjectLike value, Object key) {
    var result = VmValue.export(VmUtils.readMember(value, key));
    return result instanceof PNull ? null : (String) result;
  }

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Inspect the `caused by` ExternalReaderProcessException message for the reader's stderr/exit reason.
2. Verify the external reader binary is installed, executable, and on PATH for the process evaluating the Pkl code.
3. Test the reader standalone (run it manually) to confirm it can serve the requested URIs.
4. Check reader credentials/network access if the reader proxies a remote backend.
5. Pin a compatible reader version after upgrading pkl.

# verify the external reader is available before evaluating
command -v my-external-reader || { echo 'external reader not installed'; exit 1; }
my-external-reader --version

When it happens

Trigger: Resolving a glob import (glob: URI handled by an external reader) where GlobResolver.resolveGlob or the subsequent module resolution invokes the external reader process and that process exits abnormally, times out, or reports an error.

Common situations: Using a custom external reader (e.g. fetching config from a service) that is not installed/on PATH, crashes on start, or fails authenticating against its backend; the reader binary mismatched after an upgrade.

Related errors

• externalReaderFailure
• externalReaderFailure
• externalReaderFailure
• External reader process has already been closed.
• externalReaderAlreadyTerminated

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