apple/pkl · error · VmException

ioErrorLoadingModule

ioErrorLoadingModule

Error message

ioErrorLoadingModule

What it means

During import analysis, reading the module for parsing threw an IOException; Pkl rethrows ioErrorLoadingModule with the module URI. It means the module could not be loaded at all (I/O failure), not that it failed to parse.

Source

Thrown at pkl-core/src/main/java/org/pkl/core/runtime/VmImportAnalyzer.java:95

      analyzeSingle(imprt.moduleUri, imprt.resolvedModuleKey, context, imports, resolvedImports);
    }
  }

  private static Set<ImportEntry> collectImports(
      ResolvedModuleKey resolvedModuleKey,
      ModuleResolver moduleResolver,
      SecurityManager securityManager) {
    List<Entry> importsAndReads;
    var moduleKey = resolvedModuleKey.getOriginal();
    try {
      importsAndReads = ImportsAndReadsParser.parse(moduleKey, resolvedModuleKey);
    } catch (VmException err) {
      throw new VmExceptionBuilder()
          .evalError("cannotAnalyzeBecauseSyntaxError", moduleKey.getUri())
          .wrapping(err)
          .build();
    } catch (IOException err) {
      throw new VmExceptionBuilder().evalError("ioErrorLoadingModule", moduleKey.getUri()).build();
    }
    var result = new HashSet<ImportEntry>();
    for (var entry : importsAndReads) {
      if (!entry.isModule()) {
        continue;
      }
      try {
        if (entry.isGlob()) {
          var theModuleKey =
              moduleResolver.resolve(moduleKey.resolveUri(IoUtils.toUri(entry.stringValue())));
          var elements =
              GlobResolver.resolveGlob(
                  securityManager,
                  theModuleKey,
                  moduleKey,
                  moduleKey.getUri(),
                  entry.stringValue());
          for (var globElement : elements.values()) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

  1. Verify the module file exists and is readable at the reported URI
  2. Check file permissions and network/file-system availability
  3. Fix the environment/path mapping for the URI scheme used

Example fix

null
Defensive patterns

Strategy: retry

Validate before calling

if (!fs.existsSync(moduleUriToPath(uri))) throw new Error('module unreadable: ' + uri)

Try / catch

try { analyzeImports(uri) } catch (e) { if (e.code === 'ioErrorLoadingModule') { retryWithBackoff(() => analyzeImports(uri)) } else throw e }

Prevention

When it happens

Trigger: IOException in ImportsAndReadsParser.parse() during collectImports: unreadable file, broken reader/external process, network path problem for the given module URI.

Common situations: File deleted or permissions changed between resolution and read; network filesystem down; bad environment mapping causing an unreadable path.

Understand the failure class

Background: "failed to read file", EACCES, ENOENT and "could not read <path>" errors: when a program can't read a file from disk — this error's family across 49 libraries.

Related errors

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