apple/pkl · error · DocGeneratorBugException

Error serializing `$path`.

Error message

Error serializing `$path`.

What it means

PackageDataGenerator.write serializes a PackageData object to JSON with kotlinx.serialization before writing to disk; if encoding throws a SerializationException it is wrapped in a DocGeneratorBugException with this message. This means the in-memory PackageData could not be converted to JSON (not a file-system problem).

Solutions

1. Check the wrapped SerializationException cause to see which field failed to encode
2. Regenerate the PackageData from source modules instead of reusing modified instances
3. If reproducible, report/inspect as a pkl-doc bug — valid PackageData should always serialize

Example fix

// before
packageData.write(path) // DocGeneratorBugException: Error serializing
// after
try {
  packageData.write(path)
} catch (e: DocGeneratorBugException) {
  logger.error("serialization failed", e.cause) // SerializationException details
}

try { packageData.write(path) } catch (e: DocGeneratorBugException) { if (e.cause is SerializationException) { logger.error("PackageData not serializable", e.cause) } else throw e }

When it happens

Trigger: Calling PackageDataGenerator.write(path) when json.encodeToString(this) throws SerializationException, typically because the PackageData content violates the serializer's expectations (e.g. unsupported or null-illegal values).

Common situations: Bugs in pkl-doc itself producing invalid PackageData; custom/patched data structures fed into the generator; incompatible kotlinx.serialization configuration.

Understand the failure class

Background: json.Marshal / "failed to marshal" errors in Go: why "unsupported type" happens and how to fix it — this error's family across 22 libraries.

Related errors

• array
• array
• Cannot parse ` ` as number.
• cannotRenderNonScalarMap
• cannotRenderNonStringMap

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

Appendix: source

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

  constructor(
    pkg: DocPackage
  ) : this(
    PackageRef(pkg.name, pkg.uri, pkg.version),
    getDocCommentSummary(pkg.overview),
    pkg.docPackageInfo.annotations.deprecation,
    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
)

View on GitHub (pinned to f3efcbfc9b)