apple/pkl · error

externalReaderFailure

externalReaderFailure

Error message

externalReaderFailure

What it means

Thrown when a globbed read must be resolved via an external reader process and that process fails, mirroring the import-glob case. The ExternalReaderProcessException is attached as the cause; the glob pattern itself is fine.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/expression/unary/ReadGlobNode.java:109

              globPattern);
      var builder = new VmObjectBuilder(resolvedElements.size());
      for (var entry : resolvedElements.entrySet()) {
        builder.addEntry(entry.getKey(), getMemberNode());
      }
      cachedResult = builder.toMapping(resolvedElements);
      cachedResults.put(globPattern, cachedResult);
      return cachedResult;
    } catch (IOException e) {
      throw exceptionBuilder().evalError("ioErrorResolvingGlob", globPattern).withCause(e).build();
    } catch (SecurityManagerException | HttpClientException | URISyntaxException e) {
      throw exceptionBuilder().withCause(e).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

  1. Inspect the cause to determine how the external reader process failed.
  2. Run the reader executable manually with sample input to reproduce the failure.
  3. Fix the externalReaders configuration (command path/args) in the project settings.
  4. Fall back to explicit individual reads for that scheme.
Defensive patterns

Strategy: try-catch

Validate before calling

// verify reader handles glob listing requests before relying on read*

Try / catch

try {
  readGlob('ext://...')
} catch (e) {
  if (e.code === 'externalReaderFailure') {
    // check e.cause; repair reader config or list resources explicitly
  }
  throw e
}

Prevention

When it happens

Trigger: Calling `read*("ext://.../*.x")` for a scheme handled by an external reader whose process fails to start or errors during glob listing in ReadGlobNode.read.

Common situations: External reader executable missing or crashing, misconfigured pkl.execution.externalReaders, reader incompatible with glob listing.

Related errors

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