{"record":{"id":"2f7ae1936eccc1c5","repo":"apple/pkl","slug":"externalreaderdoesnotsupportscheme","errorCode":"externalReaderDoesNotSupportScheme","errorMessage":"externalReaderDoesNotSupportScheme","messagePattern":"externalReaderDoesNotSupportScheme","errorType":"error_code","errorClass":"ExternalReaderProcessException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/module/ModuleKeyFactories.java","lineNumber":293,"sourceCode":"      this.evaluatorId = evaluatorId;\n    }\n\n    private synchronized ExternalModuleResolver getResolver()\n        throws ExternalReaderProcessException {\n      if (resolver != null) {\n        return resolver;\n      }\n\n      resolver = process.getModuleResolver(evaluatorId);\n      return resolver;\n    }\n\n    public Optional<ModuleKey> create(URI uri) throws ExternalReaderProcessException, IOException {\n      if (!scheme.equalsIgnoreCase(uri.getScheme())) return Optional.empty();\n\n      var spec = process.getModuleReaderSpec(scheme);\n      if (spec == null) {\n        throw new ExternalReaderProcessException(\n            ErrorMessages.create(\"externalReaderDoesNotSupportScheme\", \"module\", scheme));\n      }\n\n      return Optional.of(ModuleKeys.externalResolver(uri, spec, getResolver()));\n    }\n\n    @Override\n    public void close() {\n      process.close();\n    }\n  }\n}\n","sourceCodeStart":275,"sourceCodeEnd":306,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/module/ModuleKeyFactories.java#L275-L306","documentation":"When resolving a URI handled by an external reader, ModuleKeyFactories.first asks the reader process for its module reader spec for the scheme. If the process returns null, the reader does not actually support that scheme for modules, and ExternalReaderProcessException externalReaderDoesNotSupportScheme is thrown.","triggerScenarios":"An external reader process is registered for a scheme, a module URI with that scheme is resolved, but process.getModuleReaderSpec(scheme) returns null (reader only supports resources, not modules, or dropped support in a new version).","commonSituations":"External reader supports resource reads but not module reads; reader binary updated and removed module support; scheme registered with the wrong reader in the CLI/config; typo'd scheme routed to the wrong reader process.","solutions":["Update the external reader to one that provides a module reader spec for the scheme, or register a reader that supports modules","Check the reader's --version and supported capabilities/schemes output","If only resource reading is needed, avoid referencing the scheme as a module URI (use the resource form instead)","Verify the reader registration config maps the scheme to the intended reader"],"exampleFix":"// before (reader lacks module support)\npkl test @mytool:///config.pkl   // externalReaderDoesNotSupportScheme\n// after\npkl test --schema https://mytool.example/schema pkl-config:///config.pkl","handlingStrategy":"validation","validationCode":"if (process.getModuleReaderSpec(uri.getScheme()) == null) throw new IllegalStateException(\"reader \" + scheme + \" does not support modules\");","typeGuard":"boolean readerSupportsModules(ExternalReaderProcess p, String scheme) { return p.getModuleReaderSpec(scheme) != null; }","tryCatchPattern":"try { keyFactory.create(uri); } catch (ExternalReaderProcessException e) { if (e.getMessage().contains(\"externalReaderDoesNotSupportScheme\")) { throw new ConfigurationException(\"Reader for \" + scheme + \" does not support modules\"); } throw e; }","preventionTips":["Check reader capabilities/scheme support before registering it","Keep the external reader binary up to date","Register separate readers for resource vs module handling if needed","Smoke-test external reader schemes in CI"],"tags":["java","external-reader","scheme","module-resolution"],"backgroundTag":"external-reader-unsupported-scheme","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}