apple/pkl · error · DocGeneratorBugException

Error deserializing ` `.

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.

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 ` `.
• array
• array
• Cannot parse ` ` as number.
• cannotRenderValue

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

Appendix: 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)