{"record":{"id":"aef8d6784e8f4753","repo":"apple/pkl","slug":"externalreaderfailure","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/ModuleResolver.java","lineNumber":88,"sourceCode":"      throw new VmExceptionBuilder()\n          .withOptionalLocation(importNode)\n          .bug(\"Cannot resolve relative URI `%s`.\", moduleUri)\n          .build();\n    }\n\n    var normalized = moduleUri.normalize();\n    for (var factory : factories) {\n      Optional<ModuleKey> key;\n      try {\n        key = factory.create(normalized);\n      } catch (URISyntaxException e) {\n        throw new VmExceptionBuilder()\n            .withOptionalLocation(importNode)\n            .evalError(\"invalidModuleUri\", moduleUri)\n            .withHint(e.getReason())\n            .build();\n      } catch (ExternalReaderProcessException e) {\n        throw new VmExceptionBuilder()\n            .withOptionalLocation(importNode)\n            .evalError(\"externalReaderFailure\")\n            .withCause(e)\n            .build();\n      } catch (IOException e) {\n        throw new VmExceptionBuilder()\n            .withOptionalLocation(importNode)\n            .evalError(\"ioErrorLoadingModule\")\n            .withCause(e)\n            .build();\n      }\n      if (key.isPresent()) return key.get();\n    }\n\n    throw new VmExceptionBuilder()\n        .evalError(\"noModuleLoaderRegistered\", moduleUri)\n        .withOptionalLocation(importNode)\n        .build();","sourceCodeStart":70,"sourceCodeEnd":106,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/ModuleResolver.java#L70-L106","documentation":"If a module URI is handled by an external reader (a user-registered external reader process, e.g. via pkl release external readers or custom `externalReader` wiring) and that process fails, ModuleResolver turns the ExternalReaderProcessException into the eval error 'externalReaderFailure' with the underlying exception as cause.","triggerScenarios":"resolve() encounters a URI whose scheme is claimed by an external reader and factory.create() throws ExternalReaderProcessException — the external reader process crashed, exited non-zero, or produced invalid output.","commonSituations":"Custom external reader binaries not on PATH, crashing on the requested module, misconfigured reader command, or reader incompatible with the Pkl CLI version.","solutions":["Inspect the cause attached to the error for the external reader's stderr/exit status.","Verify the external reader command works standalone when invoked with the same URI.","Fix the reader registration (path/command) in your CLI config or project settings; update the reader to match your Pkl version."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// smoke-test the external reader: run its command with a known URI and check exit code 0 before evaluation.","typeGuard":null,"tryCatchPattern":"catch (VmException e) { if (\"externalReaderFailure\".equals(e.getCode())) { log(e.getCause()); /* fall back to a local module or abort */ } }","preventionTips":["Verify external reader binaries are installed, executable, and on PATH.","Pin reader versions compatible with your Pkl CLI version."],"tags":["external-reader","module-resolution","process"],"backgroundTag":"upstream-api-error","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"}