{"record":{"id":"420320d258e9d14f","repo":"apple/pkl","slug":"i-o-error-generating-documentation-e","errorCode":null,"errorMessage":"I/O error generating documentation: $e","messagePattern":"I/O error generating documentation: \\$e","errorType":"exception","errorClass":"DocGeneratorBugException","httpStatus":null,"severity":"error","filePath":"pkl-doc/src/main/kotlin/org/pkl/doc/DocGenerator.kt","lineNumber":248,"sourceCode":"                launch { searchIndexGenerator.generate(docPackage) }\n                launch { packageDataGenerator.generate(docPackage) }\n              }\n            }\n          }\n        }\n\n        writeOutputLine(\"Generated HTML for packages\")\n\n        createCurrentDirectories(currentPackages, existingCurrentPackages)\n        searchIndexGenerator.generateSiteIndex(currentPackages)\n        htmlGenerator.generateSite(currentPackages)\n        runtimeDataGenerator.generate(newlyGeneratedPackages)\n\n        writeOutputLine(\"Wrote package runtime data files\")\n\n        docMigrator.updateDocsiteVersion()\n      } catch (e: IOException) {\n        throw DocGeneratorBugException(\"I/O error generating documentation: $e\", e)\n      }\n    }\n\n  private fun DocPackage.deletePackageDir() {\n    outputDir.resolve(IoUtils.encodePath(\"$name/$version\")).deleteRecursively()\n  }\n\n  private fun createCurrentDirectories(\n    currentPackages: List<PackageData>,\n    existingCurrentPackages: List<PackageData>,\n  ) {\n    val packagesToCreate = currentPackages - existingCurrentPackages.toSet()\n    for (packageData in packagesToCreate) {\n      val basePath = outputDir.resolve(packageData.ref.pkg.pathEncoded)\n      val src = basePath.resolve(packageData.ref.version)\n      val dst = basePath.resolve(CURRENT_DIRECTORY_NAME)\n\n      if (noSymlinks) {","sourceCodeStart":230,"sourceCodeEnd":266,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-doc/src/main/kotlin/org/pkl/doc/DocGenerator.kt#L230-L266","documentation":"DocGenerator wraps any IOException thrown during documentation generation into a DocGeneratorBugException with this message. It signals that a file-system I/O operation (reading or writing docsite files) failed unexpectedly while generating docs; the original IOException is attached as the cause.","triggerScenarios":"An IOException is raised anywhere inside DocGenerator.run's try block, e.g. failing to create or write files under outputDir (disk full, permissions, path is a directory, removed mid-run).","commonSituations":"Read-only CI workspace or outputDir; insufficient disk space; output path locked by another process; outputDir deleted or permissions changed while generation runs.","solutions":["Inspect the wrapped cause (IOException) message for the real file and reason","Check write permissions and free disk space for the output directory","Ensure outputDir exists, is writable, and no other process holds it; re-run"],"exampleFix":"// before\ndocGenerator.run(executor) // DocGeneratorBugException: I/O error...\n// after\ntry {\n  docGenerator.run(executor)\n} catch (e: DocGeneratorBugException) {\n  logger.error(\"doc generation failed\", e.cause) // real IOException\n}","handlingStrategy":"try-catch","validationCode":"require(outputDir.isDirectory && outputDir.isWritable()) { \"outputDir not writable\" }","typeGuard":null,"tryCatchPattern":"try { docGenerator.run(executor) } catch (e: DocGeneratorBugException) { val ioCause = e.cause as? IOException; logger.error(\"doc I/O failure\", ioCause) }","preventionTips":["Ensure the output directory exists, is writable, and has free disk space","Avoid concurrent doc generation into the same output dir","Run generation in CI with a writable workspace volume"],"tags":["io","filesystem","wrapped-exception"],"backgroundTag":"file-write-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"}