{"record":{"id":"fd29dc7250917b00","repo":"apple/pkl","slug":"docsite-is-not-up-to-date-expected-docmigrator","errorCode":null,"errorMessage":"Docsite is not up to date. Expected: ${DocMigrator.CURRENT_VERSION}. Found: ${docMigrator.docsiteVersion}. Use DocMigrator to migrate the site.","messagePattern":"Docsite is not up to date\\. Expected: (.+?)\\. Found: (.+?)\\. Use DocMigrator to migrate the site\\.","errorType":"exception","errorClass":"DocGeneratorException","httpStatus":null,"severity":"error","filePath":"pkl-doc/src/main/kotlin/org/pkl/doc/DocGenerator.kt","lineNumber":189,"sourceCode":"      run(executor)\n    } finally {\n      // can't use close() because we compile with --release 17\n      executor.shutdown()\n      try {\n        executor.awaitTermination(Long.MAX_VALUE, TimeUnit.NANOSECONDS)\n      } catch (e: InterruptedException) {\n        executor.shutdownNow()\n        throw e\n      }\n    }\n  }\n\n  /** Runs this documentation generator with the given executor. */\n  fun run(executor: Executor) =\n    runBlocking(executor.asCoroutineDispatcher()) {\n      try {\n        if (!docMigrator.isUpToDate) {\n          throw DocGeneratorException(\n            \"Docsite is not up to date. Expected: ${DocMigrator.CURRENT_VERSION}. Found: ${docMigrator.docsiteVersion}. Use DocMigrator to migrate the site.\"\n          )\n        }\n        val searchIndexGenerator = SearchIndexGenerator(outputDir, consoleOut)\n        val packageDataGenerator = PackageDataGenerator(outputDir, consoleOut)\n        val runtimeDataGenerator =\n          RuntimeDataGenerator(descendingVersionComparator, outputDir, consoleOut)\n\n        val newlyGeneratedPackages = docPackages.map(::PackageData).sortedBy { it.ref.pkg }\n        val currentSearchIndex = searchIndexGenerator.getCurrentSearchIndex()\n\n        writeOutputLine(\"Loaded current search index\")\n\n        val existingCurrentPackages = getCurrentPackages(currentSearchIndex)\n\n        writeOutputLine(\"Fetched latest packages\")\n\n        val currentPackages =","sourceCodeStart":171,"sourceCodeEnd":207,"githubUrl":"https://github.com/apple/pkl/blob/f3efcbfc9b60d30053b0536d664948d7aa1b8673/pkl-doc/src/main/kotlin/org/pkl/doc/DocGenerator.kt#L171-L207","documentation":"The DocGenerator checks that the existing output docsite's format version matches DocMigrator.CURRENT_VERSION before regenerating. If the on-disk docsite was produced by an older (or newer) pkl-doc version, it refuses to run and instructs the user to run DocMigrator to migrate the site to the expected version.","triggerScenarios":"Calling DocGenerator.run(executor) when docMigrator.isUpToDate is false — i.e. the docsite version file in the output directory records a version different from CURRENT_VERSION.","commonSituations":"Upgrading pkl-doc and re-running doc generation on an old output directory; sharing a docsite output checked into git across team members with different tool versions; CI cache restoring a stale docsite.","solutions":["Run the DocMigrator to migrate the existing docsite to the current version","Delete the stale output directory and regenerate the documentation from scratch","Align the pkl-doc version used to generate the site originally with the current one"],"exampleFix":"// before\ndocGenerator.run(executor) // fails: docsite version mismatch\n// after\ndocMigrator.migrate() // or: delete outputDir and regenerate\ndocGenerator.run(executor)","handlingStrategy":"validation","validationCode":"if (!docMigrator.isUpToDate) {\n  docMigrator.migrate() // or delete outputDir before generating\n}","typeGuard":null,"tryCatchPattern":"try { docGenerator.run(executor) } catch (e: DocGeneratorException) { if (e.message?.contains(\"Docsite is not up to date\") == true) { deleteRecursively(outputDir); docGenerator.run(executor) } else throw e }","preventionTips":["Check docMigrator.isUpToDate before every generation run","Pin the pkl-doc version in CI to avoid docsite version skew","Treat the docsite output dir as generated-only (never edit by hand)"],"tags":["versioning","migration","stale-output"],"backgroundTag":"version-incompatible","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"}