apple/pkl · error · DocGeneratorBugException

I/O error generating documentation: $e

Error message

I/O error generating documentation: $e

What it means

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.

Source

Thrown at pkl-doc/src/main/kotlin/org/pkl/doc/DocGenerator.kt:248

                launch { searchIndexGenerator.generate(docPackage) }
                launch { packageDataGenerator.generate(docPackage) }
              }
            }
          }
        }

        writeOutputLine("Generated HTML for packages")

        createCurrentDirectories(currentPackages, existingCurrentPackages)
        searchIndexGenerator.generateSiteIndex(currentPackages)
        htmlGenerator.generateSite(currentPackages)
        runtimeDataGenerator.generate(newlyGeneratedPackages)

        writeOutputLine("Wrote package runtime data files")

        docMigrator.updateDocsiteVersion()
      } catch (e: IOException) {
        throw DocGeneratorBugException("I/O error generating documentation: $e", e)
      }
    }

  private fun DocPackage.deletePackageDir() {
    outputDir.resolve(IoUtils.encodePath("$name/$version")).deleteRecursively()
  }

  private fun createCurrentDirectories(
    currentPackages: List<PackageData>,
    existingCurrentPackages: List<PackageData>,
  ) {
    val packagesToCreate = currentPackages - existingCurrentPackages.toSet()
    for (packageData in packagesToCreate) {
      val basePath = outputDir.resolve(packageData.ref.pkg.pathEncoded)
      val src = basePath.resolve(packageData.ref.version)
      val dst = basePath.resolve(CURRENT_DIRECTORY_NAME)

      if (noSymlinks) {

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Inspect the wrapped cause (IOException) message for the real file and reason
2. Check write permissions and free disk space for the output directory
3. Ensure outputDir exists, is writable, and no other process holds it; re-run

Example fix

// before
docGenerator.run(executor) // DocGeneratorBugException: I/O error...
// after
try {
  docGenerator.run(executor)
} catch (e: DocGeneratorBugException) {
  logger.error("doc generation failed", e.cause) // real IOException
}

require(outputDir.isDirectory && outputDir.isWritable()) { "outputDir not writable" }

try { docGenerator.run(executor) } catch (e: DocGeneratorBugException) { val ioCause = e.cause as? IOException; logger.error("doc I/O failure", ioCause) }

When it happens

Trigger: 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).

Common situations: Read-only CI workspace or outputDir; insufficient disk space; output path locked by another process; outputDir deleted or permissions changed while generation runs.

Understand the failure class

Background: "failed to write file", "Could not save figure", "Error saving remote file" — file write failed: causes and fixes across languages and libraries — this error's family across 38 libraries.

Related errors

• ioErrorLoadingModule
• external read failure:
• e.getMessage()
• ioErrorWritingTestOutputFile
• ioErrorReadingTestOutputFile

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