apple/pkl · error

externalReaderFailure

externalReaderFailure

Error message

externalReaderFailure

What it means

An external reader process (custom `read`/module resource reader launched as a subprocess) failed during import resolution. Pkl wraps this as `externalReaderFailure` with the process's exception as the cause, since the built-in evaluator cannot continue without the reader's output.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/builder/AstBuilder.java:3272

          .withSourceSection(createSourceSection(ctx))
          .build();
    } catch (IOException e) {
      throw exceptionBuilder()
          .evalError("ioErrorLoadingModule", importUri)
          .withCause(e)
          .withSourceSection(createSourceSection(ctx))
          .build();
    } catch (SecurityManagerException | PackageLoadError e) {
      throw exceptionBuilder().withSourceSection(createSourceSection(ctx)).withCause(e).build();
    } catch (VmException e) {
      throw exceptionBuilder()
          .evalError(e.getMessage(), e.getMessageArguments())
          .withCause(e.getCause())
          .withHintBuilder(e.getHintBuilder())
          .withSourceSection(createSourceSection(ctx))
          .build();
    } catch (ExternalReaderProcessException e) {
      throw exceptionBuilder()
          .evalError("externalReaderFailure")
          .withCause(e.getCause())
          .withSourceSection(createSourceSection(ctx))
          .build();
    }

    if (!resolvedUri.isAbsolute()) {
      throw exceptionBuilder()
          .evalError("cannotHaveRelativeImport", moduleKey.getUri())
          .withSourceSection(createSourceSection(ctx))
          .build();
    }
    return resolvedUri;
  }

  private ConstLevel getConstLevel(int modifiers) {
    if (VmModifier.isConst(modifiers)) return ConstLevel.ALL;
    return symbolTable.getCurrentScope().getConstLevel();

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Inspect the cause for the reader's stderr / exit status
  2. Verify the external reader executable is installed and on PATH
  3. Run the reader manually with the same input to reproduce the failure
  4. Update or reinstall the reader tool to a compatible version

Example fix

// before: reader not installed
// $ pkl eval config.pkl -> externalReaderFailure (env reader missing)
// after
// $ pkl test -- or manually: my-env-reader get KEY
// then: pkl eval config.pkl
Defensive patterns

Strategy: try-catch

Validate before calling

// before eval, smoke-test the external reader:
// my-reader get SOME_KEY && echo ok || echo "external reader broken"

Try / catch

// Catch externalReaderFailure, read the cause's stderr/exit code, and fall back or abort with that detail

Prevention

When it happens

Trigger: An import or read routed to an external reader whose subprocess crashed, returned a non-zero exit, or produced invalid output (`ExternalReaderProcessException`).

Common situations: Third-party readers (e.g. custom environment/database readers) missing from PATH; reader script erroring on the host; incompatible reader protocol version.

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/3177628067cda469. Report an issue: GitHub.