apple/pkl · error · VmException

ioErrorLoadingModule

ioErrorLoadingModule

Error message

ioErrorLoadingModule

What it means

`VmUtils.loadSource` wraps IOExceptions from `ResolvedModuleKey.loadSource()` into an ioErrorLoadingModule evalError carrying the module URI. Pkl throws this when a module cannot be physically read during loading (network, filesystem, or resolver failure).

Source

Thrown at pkl-core/src/main/java/org/pkl/core/runtime/VmUtils.java:613

  @TruffleBoundary
  public static String builderToString(StringBuilder builder) {
    return builder.toString();
  }

  public static void checkPositive(long n) {
    if (n < 0) {
      CompilerDirectives.transferToInterpreter();
      throw new VmExceptionBuilder().evalError("expectedPositiveNumber", n).build();
    }
  }

  public static Source loadSource(ResolvedModuleKey resolvedKey) {
    try {
      var text = resolvedKey.loadSource();
      return createSource(resolvedKey.getOriginal(), text);
    } catch (IOException e) {
      throw new VmExceptionBuilder()
          .evalError("ioErrorLoadingModule", resolvedKey.getOriginal().getUri())
          .withCause(e)
          .build();
    }
  }

  public static Source createSource(ModuleKey moduleKey, String text) {
    return Source.newBuilder("pkl", text, moduleKey.getUri().toString())
        .mimeType(VmLanguage.MIME_TYPE)
        .uri(moduleKey.getUri())
        .cached(false)
        .build();
  }

  public static VmException toVmException(
      ParserError e, String text, URI moduleUri, String moduleName) {
    var source =
        Source.newBuilder("pkl", text, moduleName)

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Check the module URI/path is correct and the file exists.
2. Verify filesystem read permissions for the process.
3. For remote modules, check network connectivity and registry/package availability.
4. Ensure all dependencies (Pkl packages, project files) are vendored or cached before running in CI/offline.

Example fix

// before
import "config/prod_config.pkl"
// after (file was renamed)
import "config/prod.config.pkl"

// check the module file exists and is readable before import/eval
fs.accessSync(modulePath, fs.constants.R_OK)

function moduleIsLoadable(uri) { try { fs.statSync(toPath(uri)); return true; } catch { return false; } }

try { loadSource(resolvedKey) } catch (e) { if (e.message.includes('ioErrorLoadingModule')) { /* check path/network, then retry */ } throw e; }

When it happens

Trigger: Importing/evaluating a module whose resolved URI cannot be loaded: file deleted or unreadable, remote fetch failing (network down, HTTP error on package/module fetch), bad permissions.

Common situations: Missing project files after a fresh clone, mistyped paths in imports, offline environments trying to fetch package modules, filesystem permission changes in CI containers.

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

• ioErrorLoadingModule
• Is a directory
• cannotEvaluateNonFileBasedTestModule
• ioErrorWritingTestOutputFile
• ioErrorReadingTestOutputFile

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