{"record":{"id":"e832d3251dba7f65","repo":"apple/pkl","slug":"pkldoc-website-model-is-too-old-found-docmigra","errorCode":null,"errorMessage":"pkldoc website model is too old (found: ${docMigrator.docsiteVersion}, required: ${DocMigrator.CURRENT_VERSION}). Run `pkldoc --migrate` to migrate the website.","messagePattern":"pkldoc website model is too old \\(found: (.+?), required: (.+?)\\)\\. Run `pkldoc --migrate` to migrate the website\\.","errorType":"exception","errorClass":"CliException","httpStatus":null,"severity":"error","filePath":"pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt","lineNumber":153,"sourceCode":"          val elementAssetUri = self.resolve(element.name)\n          if (element.isDirectory) {\n            addAll(elementAssetUri.gatherModulesRecursively())\n          } else if (element.name.endsWith(\".pkl\")) {\n            add(elementAssetUri)\n          }\n        }\n      }\n    }\n    return toPackageAssetUri(\"/\").gatherModulesRecursively()\n  }\n\n  override fun doRun() {\n    if (options.migrate) {\n      docMigrator.run()\n      return\n    }\n    if (!docMigrator.isUpToDate) {\n      throw CliException(\n        \"pkldoc website model is too old (found: ${docMigrator.docsiteVersion}, required: ${DocMigrator.CURRENT_VERSION}). Run `pkldoc --migrate` to migrate the website.\"\n      )\n    }\n    val docsiteInfoModuleUris = mutableListOf<URI>()\n    val packageInfoModuleUris = mutableListOf<URI>()\n    val regularModuleUris = mutableListOf<URI>()\n    val pklProjectPaths = mutableSetOf<Path>()\n    val packageUris = mutableListOf<PackageUri>()\n    for (moduleUri in options.base.normalizedSourceModules) {\n      if (moduleUri.scheme == \"file\") {\n        val dir = moduleUri.toPath().parent\n        val projectFile = dir.getProjectFile(options.base.normalizedRootDir)\n        if (projectFile != null) {\n          pklProjectPaths.add(projectFile)\n        }\n      }\n      when {\n        moduleUri.path?.endsWith(\"/docsite-info.pkl\", ignoreCase = true) ?: false ->","sourceCodeStart":135,"sourceCodeEnd":171,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt#L135-L171","documentation":"pkldoc maintains a persistent website model whose schema version is tracked by DocMigrator. If the existing generated docsite was produced by an older pkldoc version, generation refuses to continue until the site is migrated to the current model version.","triggerScenarios":"Running `pkldoc generate` (or run/serve) when docMigrator.isUpToDate is false, i.e. the stored docsite version < DocMigrator.CURRENT_VERSION — typically after upgrading the pkldoc tool over an existing docsite directory.","commonSituations":"Upgrading pkldoc in CI and re-running generation over a cached docsite output directory from an older version; stale output committed to the repo.","solutions":["Run `pkldoc --migrate` once to migrate the existing website model to the current version, then rerun the command.","Alternatively delete the stale docsite output directory and regenerate from scratch.","Pin pkldoc version in CI to avoid surprise migrations mid-build."],"exampleFix":"// before\npkldoc generate . // fails: model too old\n// after\npkldoc --migrate\npkldoc generate .","handlingStrategy":"try-catch","validationCode":"// detect staleness before generating\n// if docsite metadata version file < current pkldoc version => run pkldoc --migrate first","typeGuard":null,"tryCatchPattern":"try {\n  pkldocGenerate()\n} catch (e: CliException) {\n  if (e.message?.contains(\"website model is too old\") == true) {\n    exec(\"pkldoc\", \"--migrate\")\n    pkldocGenerate()\n  } else throw e\n}","preventionTips":["Pin the pkldoc version in CI to match the version that produced the docsite.","Regenerate the docsite from scratch after major pkldoc upgrades instead of patching in place.","Add a migration step to the release pipeline when upgrading pkldoc."],"tags":["cli","migration","versioning","documentation"],"backgroundTag":"incompatible-source-type","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"}