apple/pkl · error · CliException

pkldoc website model is too old

Error message

pkldoc website model is too old (found: ${docMigrator.docsiteVersion}, required: ${DocMigrator.CURRENT_VERSION}). Run `pkldoc --migrate` to migrate the website.

What it means

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.

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.

Example fix

// before
pkldoc generate . // fails: model too old
// after
pkldoc --migrate
pkldoc generate .

Defensive patterns

Strategy: try-catch

Validate before calling

// detect staleness before generating
// if docsite metadata version file < current pkldoc version => run pkldoc --migrate first

Try / catch

try {
  pkldocGenerate()
} catch (e: CliException) {
  if (e.message?.contains("website model is too old") == true) {
    exec("pkldoc", "--migrate")
    pkldocGenerate()
  } else throw e
}

Prevention

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.

When it happens

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

Common situations: Upgrading pkldoc in CI and re-running generation over a cached docsite output directory from an older version; stale output committed to the repo.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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

Appendix: source

Thrown at pkl-doc/src/main/kotlin/org/pkl/doc/CliDocGenerator.kt:153

          val elementAssetUri = self.resolve(element.name)
          if (element.isDirectory) {
            addAll(elementAssetUri.gatherModulesRecursively())
          } else if (element.name.endsWith(".pkl")) {
            add(elementAssetUri)
          }
        }
      }
    }
    return toPackageAssetUri("/").gatherModulesRecursively()
  }

  override fun doRun() {
    if (options.migrate) {
      docMigrator.run()
      return
    }
    if (!docMigrator.isUpToDate) {
      throw CliException(
        "pkldoc website model is too old (found: ${docMigrator.docsiteVersion}, required: ${DocMigrator.CURRENT_VERSION}). Run `pkldoc --migrate` to migrate the website."
      )
    }
    val docsiteInfoModuleUris = mutableListOf<URI>()
    val packageInfoModuleUris = mutableListOf<URI>()
    val regularModuleUris = mutableListOf<URI>()
    val pklProjectPaths = mutableSetOf<Path>()
    val packageUris = mutableListOf<PackageUri>()
    for (moduleUri in options.base.normalizedSourceModules) {
      if (moduleUri.scheme == "file") {
        val dir = moduleUri.toPath().parent
        val projectFile = dir.getProjectFile(options.base.normalizedRootDir)
        if (projectFile != null) {
          pklProjectPaths.add(projectFile)
        }
      }
      when {
        moduleUri.path?.endsWith("/docsite-info.pkl", ignoreCase = true) ?: false ->

View on GitHub (pinned to f3efcbfc9b)