apple/pkl · error

ioErrorLoadingModule

ioErrorLoadingModule

Error message

ioErrorLoadingModule ${importUri}

What it means

Thrown when reading/fetching an imported module from its resolved URI raised an IOException — the URI was valid but the module could not be loaded from disk/network. The original IOException is attached as the cause.

Solutions

  1. Check the file/directory path in the import and the attached cause message
  2. Verify the imported file exists relative to the importing module
  3. Check network access/proxy settings for remote imports
  4. Re-run `pkl project resolve` if dependencies are missing

Example fix

// before (file missing)
import "../shared/base.pkl"
// after
import "../common/base.pkl" // corrected path after file was moved
Defensive patterns

Strategy: try-catch

Validate before calling

// before eval, verify imported files exist:
// test -f path/to/imported.pkl || echo "missing module"

Try / catch

// CLI: pkl eval module.pkl 2>err.log; check err.log for ioErrorLoadingModule and the caused-by IOException

Prevention

When it happens

Trigger: An `import` whose target file does not exist, is a directory, or whose network fetch (http(s) module, package) failed with an I/O error during `resolveImport`.

Common situations: Typos in the module path; file moved/renamed after the import was written; offline environment when importing remote modules; missing package resources.

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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

Appendix: source

Thrown at pkl-core/src/main/java/org/pkl/core/ast/builder/AstBuilder.java:3257

      var exceptionBuilder =
          exceptionBuilder()
              .evalError("cannotFindModule", importUri)
              .withSourceSection(createSourceSection(ctx));
      var path = parsedUri.getPath();
      if (path != null && path.contains("\\")) {
        exceptionBuilder.withHint(
            "To resolve modules in nested directories, use `/` as the directory separator.");
      }
      throw exceptionBuilder.build();
    } catch (URISyntaxException e) {
      throw exceptionBuilder()
          .evalError("invalidModuleUri", importUri)
          .withHint(e.getReason())
          .withSourceSection(createSourceSection(ctx))
          .build();
    } catch (IOException e) {
      throw exceptionBuilder()
          .evalError("ioErrorLoadingModule", importUri)
          .withCause(e)
          .withSourceSection(createSourceSection(ctx))
          .build();
    } catch (SecurityManagerException | PackageLoadError e) {
      throw exceptionBuilder().withSourceSection(createSourceSection(ctx)).withCause(e).build();
    } catch (VmException e) {
      throw exceptionBuilder()
          .evalError(e.getMessage(), e.getMessageArguments())
          .withCause(e.getCause())
          .withHintBuilder(e.getHintBuilder())
          .withSourceSection(createSourceSection(ctx))
          .build();
    } catch (ExternalReaderProcessException e) {
      throw exceptionBuilder()
          .evalError("externalReaderFailure")
          .withCause(e.getCause())
          .withSourceSection(createSourceSection(ctx))

View on GitHub (pinned to f3efcbfc9b)