{"record":{"id":"444869d35ca44000","repo":"apple/pkl","slug":"externalreaderfailure-444869","errorCode":"externalReaderFailure","errorMessage":"Failed to communicate with external reader process.","messagePattern":"Failed to communicate with external reader process\\.","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/ast/expression/unary/ImportGlobNode.java","lineNumber":110,"sourceCode":"      for (var entry : resolvedElements.entrySet()) {\n        builder.addEntry(entry.getKey(), getMemberNode());\n      }\n      cachedResult = builder.toMapping(resolvedElements);\n      return cachedResult;\n    } catch (IOException e) {\n      throw exceptionBuilder().evalError(\"ioErrorResolvingGlob\", importUri).withCause(e).build();\n    } catch (SecurityManagerException | HttpClientException e) {\n      throw exceptionBuilder().withCause(e).build();\n    } catch (PackageLoadError e) {\n      throw exceptionBuilder().adhocEvalError(e.getMessage()).build();\n    } catch (InvalidGlobPatternException e) {\n      throw exceptionBuilder()\n          .evalError(\"invalidGlobPattern\", globPattern)\n          .withHint(e.getMessage())\n          .build();\n    } catch (ExternalReaderProcessException e) {\n      throw exceptionBuilder().evalError(\"externalReaderFailure\").withCause(e).build();\n    }\n  }\n}\n","sourceCodeStart":92,"sourceCodeEnd":113,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/ast/expression/unary/ImportGlobNode.java#L92-L113","documentation":"Pkl throws this when glob resolution goes through an external reader process (a custom reader handling a custom scheme) and the process fails or violates the protocol. The original ExternalReaderProcessException is attached as cause. Same family as the externalReaderFailure raised by resource reads.","triggerScenarios":"Evaluating a glob import over a scheme served by an external reader when that process crashes, times out, or returns malformed glob-element listings.","commonSituations":"Custom project reader with a bug in its glob/element handling; reader binary missing or non-executable in the environment; reader emitting output that does not match the external reader protocol.","solutions":["Inspect the cause chain for the reader's error output and fix the reader implementation.","Ensure the reader command in PklProject is executable, on PATH, and works for glob (listing) requests.","Test the reader standalone against the external reader protocol.","Reinstall or upgrade the tooling/package that provides the reader."],"exampleFix":"// before\nexternalReader = \"my-reader\"  // crashes on glob listing\n// after\n// fix reader to handle list requests, then:\nexternalReader = \"./bin/my-reader\"","handlingStrategy":"retry","validationCode":"// Before evaluation, smoke-test the external reader process:\n//   start it, send a protocol request, assert a well-formed response","typeGuard":null,"tryCatchPattern":"try {\n  return eval();\n} catch (PklException e) {\n  if (e.message?.contains(\"external reader\") == true) {\n    restartReader(); return retry();  // bounded retries\n  }\n  throw e;\n}","preventionTips":["Test external readers' glob/listing handling in CI, not only single-resource fetches.","Pin and version the reader binary; verify executability in deployment environments.","Keep reader stdout strictly protocol-conformant; send diagnostics to stderr."],"tags":["glob","external-reader","process","import","pkl"],"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"}