{"record":{"id":"3177628067cda469","repo":"apple/pkl","slug":"externalreaderfailure-317762","errorCode":"externalReaderFailure","errorMessage":"externalReaderFailure","messagePattern":"externalReaderFailure","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/builder/AstBuilder.java","lineNumber":3272,"sourceCode":"          .withSourceSection(createSourceSection(ctx))\n          .build();\n    } catch (IOException e) {\n      throw exceptionBuilder()\n          .evalError(\"ioErrorLoadingModule\", importUri)\n          .withCause(e)\n          .withSourceSection(createSourceSection(ctx))\n          .build();\n    } catch (SecurityManagerException | PackageLoadError e) {\n      throw exceptionBuilder().withSourceSection(createSourceSection(ctx)).withCause(e).build();\n    } catch (VmException e) {\n      throw exceptionBuilder()\n          .evalError(e.getMessage(), e.getMessageArguments())\n          .withCause(e.getCause())\n          .withHintBuilder(e.getHintBuilder())\n          .withSourceSection(createSourceSection(ctx))\n          .build();\n    } catch (ExternalReaderProcessException e) {\n      throw exceptionBuilder()\n          .evalError(\"externalReaderFailure\")\n          .withCause(e.getCause())\n          .withSourceSection(createSourceSection(ctx))\n          .build();\n    }\n\n    if (!resolvedUri.isAbsolute()) {\n      throw exceptionBuilder()\n          .evalError(\"cannotHaveRelativeImport\", moduleKey.getUri())\n          .withSourceSection(createSourceSection(ctx))\n          .build();\n    }\n    return resolvedUri;\n  }\n\n  private ConstLevel getConstLevel(int modifiers) {\n    if (VmModifier.isConst(modifiers)) return ConstLevel.ALL;\n    return symbolTable.getCurrentScope().getConstLevel();","sourceCodeStart":3254,"sourceCodeEnd":3290,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/builder/AstBuilder.java#L3254-L3290","documentation":"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.","triggerScenarios":"An import or read routed to an external reader whose subprocess crashed, returned a non-zero exit, or produced invalid output (`ExternalReaderProcessException`).","commonSituations":"Third-party readers (e.g. custom environment/database readers) missing from PATH; reader script erroring on the host; incompatible reader protocol version.","solutions":["Inspect the cause for the reader's stderr / exit status","Verify the external reader executable is installed and on PATH","Run the reader manually with the same input to reproduce the failure","Update or reinstall the reader tool to a compatible version"],"exampleFix":"// before: reader not installed\n// $ pkl eval config.pkl -> externalReaderFailure (env reader missing)\n// after\n// $ pkl test -- or manually: my-env-reader get KEY\n// then: pkl eval config.pkl","handlingStrategy":"try-catch","validationCode":"// before eval, smoke-test the external reader:\n// my-reader get SOME_KEY && echo ok || echo \"external reader broken\"","typeGuard":null,"tryCatchPattern":"// Catch externalReaderFailure, read the cause's stderr/exit code, and fall back or abort with that detail","preventionTips":["Install external readers and verify they are on PATH in CI images","Pin reader versions compatible with your Pkl version","Monitor reader stderr; fail fast in setup scripts"],"tags":["pkl","external-reader","subprocess","import"],"backgroundTag":"http-request-failed","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}