apple/pkl · error · DocGeneratorBugException

I/O error writing `$path`.

Error message

I/O error writing `$path`.

What it means

PackageDataGenerator.write serializes package data to JSON and writes it to disk. It wraps any IOException from creating parent directories or writing the file into a DocGeneratorBugException, since a failure here is treated as a doc-generator bug rather than expected user error. The path is shown in the message with the underlying cause attached.

Solutions

1. Check write permissions on the target output directory and its parent path.
2. Verify the output path exists and is not a directory; free disk space if low.
3. Run the generator with a user account that owns the output directory.
4. Inspect the wrapped cause exception for the exact OS-level IO failure.

Example fix

// before
path.writer().use { it.write(jsonStr) } // IOException on read-only dir
// after
require(path.parent.isDirectory && path.parent.canWrite()) { "Cannot write to ${path.parent}" }
path.writer().use { it.write(jsonStr) }

val out = File("build/docs/pkl")
check(out.isDirectory || out.mkdirs()) { "Cannot create output dir" }
check(out.canWrite()) { "Output dir not writable" }

fun isWritableDir(p: Path) = p.isDirectory() && java.nio.file.Files.isWritable(p)

try { generator.write() } catch (e: DocGeneratorBugException) { logger.error("Doc output write failed: ${e.message}", e.cause) }

When it happens

Trigger: Calling PackageDataGenerator.write when the output path's parent directories cannot be created, the path is not writable, the disk is full, or the filesystem rejects the write (permission denied, read-only volume).

Common situations: Running `pkl doc` generation into a directory the user lacks write permission for, outputting to a read-only CI workspace, or a disk-space/IO failure mid-write.

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

• I/O error writing file `$outputFile`. Cause
• Failed to write to $depsFile
• I/O error writing file `$outputFile`. Cause
• Cannot convert pkl.base#Int `$value` to kotlin.UByte…
• Cannot convert pkl.base#Int `$value` to kotlin.UInt because…

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

Appendix: source

Thrown at pkl-doc/src/main/kotlin/org/pkl/doc/PackageDataGenerator.kt:284

    pkg.docPackageInfo.sourceCode,
    pkg.docPackageInfo.sourceCodeUrlScheme,
    pkg.docPackageInfo.dependencies.map { DependencyData(PackageRef(it.name, it.uri, it.version)) },
    pkg.docModules.mapNotNull { if (it.isUnlisted) null else ModuleData(pkg, it) },
  )

  fun write(path: Path) {
    val jsonStr =
      try {
        json.encodeToString(this)
      } catch (e: SerializationException) {
        throw DocGeneratorBugException("Error serializing `$path`.", e)
      }

    try {
      path.createParentDirectories()
      path.writer().use { it.write(jsonStr) }
    } catch (e: IOException) {
      throw DocGeneratorBugException("I/O error writing `$path`.", e)
    }
  }
}

/** A package depended upon by [PackageData]. */
@Serializable
internal class DependencyData(
  /** The ref of the depended-on package. */
  val ref: PackageRef
)

/** Persisted data for a module. */
@Serializable
internal class ModuleData(
  /** The ref of this module. */
  val ref: ModuleRef,

  /** The first paragraph of the overview documentation for this module. */

View on GitHub (pinned to f3efcbfc9b)