{"record":{"id":"2ad0b2354b1daae5","repo":"apple/pkl","slug":"i-o-error-loading-pkl-module-s","errorCode":null,"errorMessage":"I/O error loading Pkl module `%s`.","messagePattern":"I/O error loading Pkl module `(.+?)`\\.","errorType":"exception","errorClass":"ExecutorException","httpStatus":null,"severity":"error","filePath":"pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java","lineNumber":113,"sourceCode":"      @Nullable Version requestedVersion,\n      @Nullable PklDistribution distribution,\n      long startTime,\n      long endTime) {\n    logger.info(\n        \"Finished evaluating Pkl module. modulePath={} outcome={} requestedVersion={} selectedVersion={} elapsedMillis={}\",\n        modulePath,\n        success,\n        requestedVersion == null ? \"n/a\" : requestedVersion.toString(),\n        distribution == null ? \"n/a\" : distribution.getVersion().toString(),\n        (endTime - startTime) / 1_000_000);\n  }\n\n  private Version detectRequestedPklVersion(Path modulePath, ExecutorOptions options) {\n    String sourceText;\n    try {\n      sourceText = Files.readString(modulePath, StandardCharsets.UTF_8);\n    } catch (IOException e) {\n      throw new ExecutorException(\n          String.format(\"I/O error loading Pkl module `%s`.\", toDisplayPath(modulePath, options)),\n          e);\n    }\n\n    var version = extractMinPklVersion(sourceText);\n    if (version != null) return version;\n\n    var availableVersions =\n        pklDistributions.stream()\n            .map(it -> it.getVersion().toString())\n            .collect(Collectors.joining(\", \"));\n\n    throw new ExecutorException(\n        String.format(\n            \"Pkl module `%s` does not state which Pkl version it requires. (Available versions: %s)%n\"\n                + \"To fix this problem, annotate the module's `amends`, `extends`, or `module` clause with `@ModuleInfo { minPklVersion = \\\"x.y.z\\\" }`.\",\n            toDisplayPath(modulePath, options), availableVersions));\n  }","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-executor/src/main/java/org/pkl/executor/EmbeddedExecutor.java#L95-L131","documentation":"detectRequestedPklVersion reads the module file as UTF-8 to extract its @ModuleInfo minPklVersion. If Files.readString throws IOException, evaluatePath aborts with ExecutorException \"I/O error loading Pkl module\". The original IOException is attached as the cause.","triggerScenarios":"The file existed at the existence check but could not be read as UTF-8 text: permission denied, file deleted between checks (race), I/O error on a network/NFS mount, or encoding issues surfaced as an IO failure.","commonSituations":"Files readable to one user but not the executor's user; modules on removable/network drives; TOCTOU races where the file is removed between the isRegularFile check and readString.","solutions":["Check file read permissions for the process user (chmod / run as the right user)","Confirm the file still exists and is on a healthy filesystem at read time","Retry on transient I/O errors if the file is on a network mount","Inspect the cause (getCause()) for the underlying IOException detail"],"exampleFix":"// before\nexecutor.evaluatePath(path, options); // may throw opaque IO error\n// after\nif (!Files.isReadable(path)) throw new IllegalStateException(\"not readable: \" + path);\ntry { executor.evaluatePath(path, options); }\ncatch (ExecutorException e) { log.error(\"module load failed\", e.getCause()); throw e; }","handlingStrategy":"try-catch","validationCode":"if (!Files.isReadable(path)) throw new IllegalStateException(\"module not readable: \" + path);\n","typeGuard":"boolean isReadableFile(Path p) { return Files.isRegularFile(p) && Files.isReadable(p); }\n","tryCatchPattern":"try { executor.evaluatePath(p, options); } catch (ExecutorException e) { if (e.getCause() instanceof IOException io) throw new ModuleLoadException(p, io); throw e; }\n","preventionTips":["Ensure the executor process user has read permission","Retry transient IO failures on network filesystems","Verify UTF-8 encoding of modules","Keep modules on local, healthy storage for evaluation"],"tags":["pkl","io","file-read"],"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-14T16:17:12.679Z"}