apple/pkl · error · ExternalReaderProcessException

externalReaderDoesNotSupportScheme

externalReaderDoesNotSupportScheme

Error message

externalReaderDoesNotSupportScheme

What it means

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.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/module/ModuleKeyFactories.java:293

      this.evaluatorId = evaluatorId;
    }

    private synchronized ExternalModuleResolver getResolver()
        throws ExternalReaderProcessException {
      if (resolver != null) {
        return resolver;
      }

      resolver = process.getModuleResolver(evaluatorId);
      return resolver;
    }

    public Optional<ModuleKey> create(URI uri) throws ExternalReaderProcessException, IOException {
      if (!scheme.equalsIgnoreCase(uri.getScheme())) return Optional.empty();

      var spec = process.getModuleReaderSpec(scheme);
      if (spec == null) {
        throw new ExternalReaderProcessException(
            ErrorMessages.create("externalReaderDoesNotSupportScheme", "module", scheme));
      }

      return Optional.of(ModuleKeys.externalResolver(uri, spec, getResolver()));
    }

    @Override
    public void close() {
      process.close();
    }
  }
}

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Update the external reader to one that provides a module reader spec for the scheme, or register a reader that supports modules
2. Check the reader's --version and supported capabilities/schemes output
3. If only resource reading is needed, avoid referencing the scheme as a module URI (use the resource form instead)
4. Verify the reader registration config maps the scheme to the intended reader

Example fix

// before (reader lacks module support)
pkl test @mytool:///config.pkl   // externalReaderDoesNotSupportScheme
// after
pkl test --schema https://mytool.example/schema pkl-config:///config.pkl

if (process.getModuleReaderSpec(uri.getScheme()) == null) throw new IllegalStateException("reader " + scheme + " does not support modules");

boolean readerSupportsModules(ExternalReaderProcess p, String scheme) { return p.getModuleReaderSpec(scheme) != null; }

try { keyFactory.create(uri); } catch (ExternalReaderProcessException e) { if (e.getMessage().contains("externalReaderDoesNotSupportScheme")) { throw new ConfigurationException("Reader for " + scheme + " does not support modules"); } throw e; }

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• external read failure:
• externalReaderDoesNotSupportScheme
• externalReaderFailure
• noModuleLoaderRegistered
• JavaType token must be parameterized.

AI-assisted analysis of apple/pkl@f3efcbfc9b (2026-09-08). Data as JSON: /api/errors/2f7ae1936eccc1c5. Report an issue: GitHub.