apple/pkl · error · DocGeneratorBugException

Error deserializing `${path.toUri()}`.

Error message

Error deserializing `${path.toUri()}`.

What it means

PackageDataGenerator.read parses the file contents as JSON into a PackageData object; if kotlinx.serialization throws a SerializationException, it is wrapped in a DocGeneratorBugException with this message. The file was readable but its contents are not valid PackageData JSON, so deserialization failed.

Source

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

  /** The modules in this package. */
  val modules: List<ModuleData> = listOf(),
) {
  companion object {
    val json = Json { serializersModule = serializers }

    fun read(path: Path): PackageData {
      val jsonStr: String =
        try {
          path.readString()
        } catch (e: IOException) {
          throw DocGeneratorBugException("I/O error reading `${path.toUri()}`.", e)
        }

      return try {
        json.decodeFromString(jsonStr)
      } catch (e: SerializationException) {
        throw DocGeneratorBugException("Error deserializing `${path.toUri()}`.", e)
      }
    }
  }

  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 =

View on GitHub (pinned to f3efcbfc9b)

Solutions

1. Regenerate the package data file from source rather than repairing it by hand
2. Validate the file is well-formed JSON matching the PackageData schema
3. Check the wrapped SerializationException for the exact field/path that failed

Example fix

// before
val data = PackageDataGenerator.read(corruptPath) // DocGeneratorBugException
// after
regeneratePackageData(corruptPath) // rewrite file from source
val data = PackageDataGenerator.read(corruptPath)

val json = Json { ignoreUnknownKeys = true }
try { json.parseToJsonElement(dataPath.readText()) } catch (e: Exception) { regeneratePackageData(dataPath) }

try { val data = PackageDataGenerator.read(path) } catch (e: DocGeneratorBugException) { if (e.cause is SerializationException) { regeneratePackageData(path) } else throw e }

When it happens

Trigger: Calling PackageDataGenerator.read(path) on a file whose JSON does not match the PackageData schema — malformed JSON, wrong fields/types, or output from an incompatible pkl-doc version.

Common situations: Hand-edited package data files; truncated writes from a previous crashed run; reading a data file produced by a different pkl-doc version with a changed schema.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

• Error deserializing `${path.toUri()}`.
• array
• object
• string
• Values of type `Duration` cannot be rendered as JSON. Value:

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