{"record":{"id":"f050a0065d4f881c","repo":"apple/pkl","slug":"externalreaderfailure-f050a0","errorCode":"externalReaderFailure","errorMessage":"externalReaderFailure","messagePattern":"externalReaderFailure","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java","lineNumber":1206,"sourceCode":"    try {\n      if (!globModuleKey.isGlobbable()) {\n        throw exceptionBuilder()\n            .evalError(\"cannotGlobUri\", importUri, importUri.getScheme())\n            .build();\n      }\n      var resolvedElements =\n          GlobResolver.resolveGlob(securityManager, globModuleKey, null, null, uriString);\n\n      var builder = new VmObjectBuilder(resolvedElements.size());\n      for (var entry : resolvedElements.entrySet()) {\n        var moduleKey = moduleResolver.resolve(entry.getValue().uri());\n        builder.addEntry(entry.getKey(), language.loadModule(moduleKey));\n      }\n      return builder.toMapping(resolvedElements);\n    } catch (IOException e) {\n      throw exceptionBuilder().evalError(\"ioErrorResolvingGlob\", importUri).withCause(e).build();\n    } catch (ExternalReaderProcessException e) {\n      throw exceptionBuilder().evalError(\"externalReaderFailure\").withCause(e).build();\n    } catch (SecurityManagerException e) {\n      throw exceptionBuilder().withCause(e).build();\n    } catch (InvalidGlobPatternException e) {\n      throw exceptionBuilder()\n          .evalError(\"invalidGlobPattern\", uriString)\n          .withHint(e.getMessage())\n          .build();\n    }\n  }\n\n  // endregion\n  // region utilities\n\n  private static @Nullable String exportNullableString(VmObjectLike value, Object key) {\n    var result = VmValue.export(VmUtils.readMember(value, key));\n    return result instanceof PNull ? null : (String) result;\n  }\n","sourceCodeStart":1188,"sourceCodeEnd":1224,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/runtime/CommandSpecParser.java#L1188-L1224","documentation":"Glob imports whose scheme is served by an external reader (a registered external filesystem reader process) fail with `externalReaderFailure` when the external reader process itself errors — CommandSpecParser catches ExternalReaderProcessException raised while resolving the glob and rethrows it as an eval error with the exception as cause.","triggerScenarios":"Resolving a glob import (glob: URI handled by an external reader) where GlobResolver.resolveGlob or the subsequent module resolution invokes the external reader process and that process exits abnormally, times out, or reports an error.","commonSituations":"Using a custom external reader (e.g. fetching config from a service) that is not installed/on PATH, crashes on start, or fails authenticating against its backend; the reader binary mismatched after an upgrade.","solutions":["Inspect the `caused by` ExternalReaderProcessException message for the reader's stderr/exit reason.","Verify the external reader binary is installed, executable, and on PATH for the process evaluating the Pkl code.","Test the reader standalone (run it manually) to confirm it can serve the requested URIs.","Check reader credentials/network access if the reader proxies a remote backend.","Pin a compatible reader version after upgrading pkl."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"# verify the external reader is available before evaluating\ncommand -v my-external-reader || { echo 'external reader not installed'; exit 1; }\nmy-external-reader --version","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Install and smoke-test external reader binaries in the evaluation environment","Keep reader credentials/network access valid","Version-lock external readers alongside the pkl version","Run the reader standalone to surface backend errors early"],"tags":["pkl","external-reader","process","glob-import"],"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"}