{"record":{"id":"902c822b4c289fd1","repo":"apple/pkl","slug":"error-serializing-path","errorCode":null,"errorMessage":"Error serializing `$path`.","messagePattern":"Error serializing `\\$path`\\.","errorType":"exception","errorClass":"DocGeneratorBugException","httpStatus":null,"severity":"error","filePath":"pkl-doc/src/main/kotlin/org/pkl/doc/PackageDataGenerator.kt","lineNumber":277,"sourceCode":"\n  constructor(\n    pkg: DocPackage\n  ) : this(\n    PackageRef(pkg.name, pkg.uri, pkg.version),\n    getDocCommentSummary(pkg.overview),\n    pkg.docPackageInfo.annotations.deprecation,\n    pkg.docPackageInfo.sourceCode,\n    pkg.docPackageInfo.sourceCodeUrlScheme,\n    pkg.docPackageInfo.dependencies.map { DependencyData(PackageRef(it.name, it.uri, it.version)) },\n    pkg.docModules.mapNotNull { if (it.isUnlisted) null else ModuleData(pkg, it) },\n  )\n\n  fun write(path: Path) {\n    val jsonStr =\n      try {\n        json.encodeToString(this)\n      } catch (e: SerializationException) {\n        throw DocGeneratorBugException(\"Error serializing `$path`.\", e)\n      }\n\n    try {\n      path.createParentDirectories()\n      path.writer().use { it.write(jsonStr) }\n    } catch (e: IOException) {\n      throw DocGeneratorBugException(\"I/O error writing `$path`.\", e)\n    }\n  }\n}\n\n/** A package depended upon by [PackageData]. */\n@Serializable\ninternal class DependencyData(\n  /** The ref of the depended-on package. */\n  val ref: PackageRef\n)\n","sourceCodeStart":259,"sourceCodeEnd":295,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-doc/src/main/kotlin/org/pkl/doc/PackageDataGenerator.kt#L259-L295","documentation":"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).","triggerScenarios":"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).","commonSituations":"Bugs in pkl-doc itself producing invalid PackageData; custom/patched data structures fed into the generator; incompatible kotlinx.serialization configuration.","solutions":["Check the wrapped SerializationException cause to see which field failed to encode","Regenerate the PackageData from source modules instead of reusing modified instances","If reproducible, report/inspect as a pkl-doc bug — valid PackageData should always serialize"],"exampleFix":"// before\npackageData.write(path) // DocGeneratorBugException: Error serializing\n// after\ntry {\n  packageData.write(path)\n} catch (e: DocGeneratorBugException) {\n  logger.error(\"serialization failed\", e.cause) // SerializationException details\n}","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try { packageData.write(path) } catch (e: DocGeneratorBugException) { if (e.cause is SerializationException) { logger.error(\"PackageData not serializable\", e.cause) } else throw e }","preventionTips":["Use PackageData instances built by the generator, not hand-modified ones","Test serialization round-trips if extending the data model","Report reproducible serialization failures as pkl-doc bugs"],"tags":["json","serialization","wrapped-exception"],"backgroundTag":"json-marshal-failed","analyzedSha":"f3efcbfc9b60d30053b0536d664948d7aa1b8673","analyzedAt":"2026-09-08T13:10:45.570Z","contentChangedAt":"2026-09-08T13:10:45.570Z","schemaVersion":2},"datasetVersion":"2026-09-17T15:17:12.973Z"}