apple/pkl · error · DocGeneratorException

Docsite is not up to date. Expected

Error message

Docsite is not up to date. Expected: ${DocMigrator.CURRENT_VERSION}. Found: ${docMigrator.docsiteVersion}. Use DocMigrator to migrate the site.

What it means

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.

Solutions

1. Run the DocMigrator to migrate the existing docsite to the current version
2. Delete the stale output directory and regenerate the documentation from scratch
3. Align the pkl-doc version used to generate the site originally with the current one

Example fix

// before
docGenerator.run(executor) // fails: docsite version mismatch
// after
docMigrator.migrate() // or: delete outputDir and regenerate
docGenerator.run(executor)

if (!docMigrator.isUpToDate) {
  docMigrator.migrate() // or delete outputDir before generating
}

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 }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• pkldoc website model is too old
• Pkl module ` ` does not state which Pkl version it…
• Pkl version ` ` requested by module ` ` is not supported…
• ` ` could not be parsed as a semantic version number.
• ` ` is too large to fit into a Version.

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

Appendix: source

Thrown at pkl-doc/src/main/kotlin/org/pkl/doc/DocGenerator.kt:189

      run(executor)
    } finally {
      // can't use close() because we compile with --release 17
      executor.shutdown()
      try {
        executor.awaitTermination(Long.MAX_VALUE, TimeUnit.NANOSECONDS)
      } catch (e: InterruptedException) {
        executor.shutdownNow()
        throw e
      }
    }
  }

  /** Runs this documentation generator with the given executor. */
  fun run(executor: Executor) =
    runBlocking(executor.asCoroutineDispatcher()) {
      try {
        if (!docMigrator.isUpToDate) {
          throw DocGeneratorException(
            "Docsite is not up to date. Expected: ${DocMigrator.CURRENT_VERSION}. Found: ${docMigrator.docsiteVersion}. Use DocMigrator to migrate the site."
          )
        }
        val searchIndexGenerator = SearchIndexGenerator(outputDir, consoleOut)
        val packageDataGenerator = PackageDataGenerator(outputDir, consoleOut)
        val runtimeDataGenerator =
          RuntimeDataGenerator(descendingVersionComparator, outputDir, consoleOut)

        val newlyGeneratedPackages = docPackages.map(::PackageData).sortedBy { it.ref.pkg }
        val currentSearchIndex = searchIndexGenerator.getCurrentSearchIndex()

        writeOutputLine("Loaded current search index")

        val existingCurrentPackages = getCurrentPackages(currentSearchIndex)

        writeOutputLine("Fetched latest packages")

        val currentPackages =

View on GitHub (pinned to f3efcbfc9b)