{"record":{"id":"a1b7d92356ba9629","repo":"apple/pkl","slug":"ioerrorloadingmodule","errorCode":"ioErrorLoadingModule","errorMessage":"ioErrorLoadingModule","messagePattern":"ioErrorLoadingModule","errorType":"error_code","errorClass":"VmException","httpStatus":null,"severity":"error","filePath":"pkl-core/src/main/java/org/pkl/core/EvaluatorImpl.java","lineNumber":457,"sourceCode":"  private ModuleSource normalizeModuleSource(ModuleSource moduleSource) {\n    if (moduleSource.getContents() != null\n        || moduleSource.getUri().isAbsolute()\n        || !moduleSource.getUri().getPath().startsWith(\"@\")) {\n      return moduleSource;\n    }\n    try {\n      if (projectFileUri != null) {\n        var moduleKey = moduleResolver.resolve(projectFileUri);\n        var uri = IoUtils.resolve(securityManager, moduleKey, moduleSource.getUri());\n        return ModuleSource.uri(uri);\n      } else {\n        throw new PackageLoadError(\"cannotResolveDependencyNoProject\");\n      }\n    } catch (URISyntaxException e) {\n      // impossible condition\n      throw PklBugException.unreachableCode();\n    } catch (IOException e) {\n      throw new VmExceptionBuilder()\n          .evalError(\"ioErrorLoadingModule\", moduleSource.getUri())\n          .build();\n    } catch (ExternalReaderProcessException | SecurityManagerException | PackageLoadError e) {\n      throw new VmExceptionBuilder().withCause(e).build();\n    }\n  }\n\n  private <T> T doEvaluate(ModuleSource moduleSource, Function<VmTyped, T> doEvaluate) {\n    return doEvaluate(\n        () -> {\n          var moduleKey = moduleResolver.resolve(normalizeModuleSource(moduleSource));\n          var module = VmLanguage.get(null).loadModule(moduleKey);\n          return doEvaluate.apply(module);\n        });\n  }\n\n  private void handleTimeout(@Nullable TimeoutTask timeoutTask) {\n    if (timeoutTask == null || timeoutTask.cancel()) return;","sourceCodeStart":439,"sourceCodeEnd":475,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-core/src/main/java/org/pkl/core/EvaluatorImpl.java#L439-L475","documentation":"ioErrorLoadingModule is an evaluation error thrown when the Pkl evaluator fails to read a module's source over I/O during module source normalization (EvaluatorImpl.normalizeModuleSource). The module URI is included in the error so the developer knows which resource could not be loaded. It wraps an IOException encountered while resolving/reading the module (e.g. from a file, HTTP, or package-backed module source).","triggerScenarios":"Calling EvaluatorImpl to evaluate a module whose source cannot be read: a file:// module path that no longer exists or is unreadable, an https:// module whose fetch fails, or a package dependency module whose cached/remote content cannot be read. normalizeModuleSource catches IOException and rethrows as VmException with code ioErrorLoadingModule.","commonSituations":"Typo in the module path passed to evaluate(); reading a Pkl file deleted or moved after the URI was computed; network outage or proxy blocking a remote module; filesystem permission changes; container images missing files bundled at build time.","solutions":["Verify the module URI exists and is readable (ls/check permissions, curl for remote URIs).","Use an absolute or correctly project-rooted path; relative module paths resolve against the importing module or base URI.","For remote modules, check network/proxy connectivity and retry.","Catch PklException/VmException with this error code and surface a clear message naming the module URI."],"exampleFix":"// before\nevaluator.evaluate(OutputFormat.text(), Paths.get(\"config/pkls/Main.pkl\"));\n// after\nPath p = Paths.get(\"config/pkls/Main.pkl\");\nif (!Files.isReadable(p)) throw new IllegalArgumentException(\"Module not readable: \" + p);\nevaluator.evaluate(OutputFormat.text(), p);","handlingStrategy":"validation","validationCode":"Path p = Paths.get(\"config/Main.pkl\");\nif (!Files.isRegularFile(p) || !Files.isReadable(p)) {\n  throw new IllegalStateException(\"Module unreadable: \" + p.toAbsolutePath());\n}","typeGuard":"static boolean isLoadableModule(URI uri) {\n  try {\n    if (\"file\".equals(uri.getScheme())) return Files.isReadable(Paths.get(uri));\n    return uri.toURL().openConnection().getInputStream() != null; // remote probe\n  } catch (IOException e) { return false; }\n}","tryCatchPattern":"try {\n  evaluator.evaluateOutputText(source);\n} catch (PklException e) {\n  if (e.getMessage().contains(\"ioErrorLoadingModule\")) {\n    throw new IOException(\"Cannot load module: \" + e.getMessage(), e);\n  }\n  throw e;\n}","preventionTips":["Check file existence/readability before evaluate()","Use absolute module paths or ModuleSource uris you control","Pre-resolve remote/package modules (network check, dependency cache warm-up)","Surface the module URI in user-facing error handling"],"tags":["io","module-loading","filesystem"],"backgroundTag":"file-read-failed","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"}