{"record":{"id":"95767d6f34af3614","repo":"apple/pkl","slug":"externalreaderfailure-95767d","errorCode":"externalReaderFailure","errorMessage":"externalReaderFailure","messagePattern":"externalReaderFailure","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/runtime/VmImportAnalyzer.java","lineNumber":154,"sourceCode":"      } catch (URISyntaxException e) {\n        throw new VmExceptionBuilder()\n            .evalError(\"invalidModuleUri\", entry.stringValue())\n            .withHint(e.getReason())\n            .withSourceSection(entry.sourceSection())\n            .build();\n      } catch (IOException e) {\n        throw new VmExceptionBuilder()\n            .evalError(\"ioErrorLoadingModule\", entry.stringValue())\n            .withCause(e)\n            .withSourceSection(entry.sourceSection())\n            .build();\n      } catch (SecurityManagerException | PackageLoadError e) {\n        throw new VmExceptionBuilder()\n            .withSourceSection(entry.sourceSection())\n            .withCause(e)\n            .build();\n      } catch (ExternalReaderProcessException e) {\n        throw new VmExceptionBuilder()\n            .withSourceSection(entry.sourceSection())\n            .evalError(\"externalReaderFailure\")\n            .withCause(e)\n            .build();\n      }\n    }\n    return result;\n  }\n\n  private record ImportEntry(URI moduleUri, ResolvedModuleKey resolvedModuleKey) {\n    private Import toImport() {\n      return new Import(resolvedModuleKey.getOriginal().getUri());\n    }\n  }\n}\n","sourceCodeStart":136,"sourceCodeEnd":170,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/VmImportAnalyzer.java#L136-L170","documentation":"Thrown during import collection in the Pkl VM when an external reader process (used to read non-standard resources via the `read()` function or imports) fails. Pkl delegates reading of custom URL schemes to external reader executables; when that process throws ExternalReaderProcessException, this evalError wraps it. The cause carries the underlying reader failure detail.","triggerScenarios":"Evaluating a module whose imports (or `read()` calls) go through an external reader registered via ExternalReader, and the reader process exits non-zero, crashes, or reports an error while resolving the resource.","commonSituations":"Custom `fileenv:`/project reader scripts that are not executable or misconfigured; external reader binary not on PATH; reader script raising its own error (bad auth, missing file inside the reader); network failures inside a custom scheme reader.","solutions":["Run the external reader command manually with the same URL to see the underlying error from the cause chain.","Verify the reader executable is installed, on PATH, and has execute permissions.","Fix the error inside the reader script itself (auth, path, network) — this error only surfaces the reader's failure.","Check the ExternalReader registration in your CLI/code matches the URL scheme being imported."],"exampleFix":"// before: reader registered for 'vault:' but vault CLI absent\nnew ExternalReader(\"vault\", List.of(\"my-vault-reader\"))\n// after: ensure binary exists and fails gracefully\nnew ExternalReader(\"vault\", List.of(\"/usr/local/bin/my-vault-reader\"))","handlingStrategy":"try-catch","validationCode":"// before evaluation\nString reader = \"my-reader\";\nProcess p = new ProcessBuilder(reader, \"--version\").start();\nif (p.waitFor() != 0) throw new IllegalStateException(\"external reader \" + reader + \" not usable\");","typeGuard":null,"tryCatchPattern":"try {\n  result = evaluator.evaluateOutputText();\n} catch (EvalException e) {\n  if (e.getMessage().contains(\"externalReaderFailure\")) {\n    // inspect e.getCause() (ExternalReaderProcessException) for reader stderr\n  }\n}","preventionTips":["Smoke-test the external reader binary in CI before running Pkl evaluations.","Register readers with absolute executable paths, not bare names.","Make reader scripts fail with clear stderr messages — they surface in the cause chain.","Keep reader exit codes informative and log stderr on failure."],"tags":["pkl","external-reader","import","process"],"backgroundTag":"file-read-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"}