agalwood/Motrix · critical · SchemaVersionTooNewError

Database schema version ${currentVersion} is newer than this

Error message

Database schema version ${currentVersion} is newer than this build supports (highest known: v${highestKnownVersion}). This usually means the database file predates the Plan A rewrite and still contains the legacy task_metadata schema.

Action: delete the database file and restart the app to recreate it on the v1 schema.
  rm '${dbPath}'

If you need the data, downgrade to the pre-Plan-A build first.

What it means

SchemaVersionTooNewError thrown by Guard A in migrate() at line 289 when the DB's schema_version row reports a version greater than HIGHEST_KNOWN_VERSION (the max version in MIGRATIONS). This means a NEWER build wrote this DB and the user has since downgraded to an older build. The migration loop would silently skip everything and the app would crash later on missing tables; this guard fails fast with a clear message.

Source

Thrown at src/core/session/migrations/index.ts:290

export function migrate(db: Database.Database): void {
  db.exec(`
    CREATE TABLE IF NOT EXISTS schema_version (
      version INTEGER PRIMARY KEY,
      applied_at INTEGER NOT NULL
    )
  `)
  assertCanonicalSchemaVersion(db)
  const row = db
    .prepare('SELECT MAX(version) AS v FROM schema_version')
    .get() as { v: number | null } | undefined
  const current = row?.v ?? 0

  // Guard A (Codex finding #7): schema_version newer than this build
  // knows about. The default migration loop would skip everything,
  // then the app would crash with cryptic "no such table" errors.
  if (current > HIGHEST_KNOWN_VERSION) {
    throw new SchemaVersionTooNewError(
      current,
      HIGHEST_KNOWN_VERSION,
      (db as unknown as { name: string }).name
    )
  }

  // Guard B (Codex finding #8): version-only check is insufficient.
  // A pre-Plan-A build also wrote schema_version=1 for its legacy v1
  // (the original `task_metadata` schema), and a half-recovered DB
  // can have schema_version >= 1 without the new tables present.
  // Run this BEFORE the migration loop so we don't try to apply v2+
  // on top of a missing baseline (v2's ALTER/INSERT would crash with
  // a cryptic "no such table" instead of the StaleSchemaError that
  // tells the user exactly what to do). Fresh DB (current == 0) gets
  // a free pass — v1 below will create the tables.
  if (current > 0) {
    const hasNewSchema =
      db

View on GitHub (pinned to 1a708ee577)

Solutions

1. Delete the DB file (path in dbPath) and restart the older build — it will recreate on its supported schema.
2. If the data is needed, re-install the newer build that wrote the DB, export the data, then downgrade and re-import.
3. Do NOT manually lower schema_version — the substantive tables are still newer and downstream checks will fail.

Example fix

# before: DB written by build supporting v4, current build only knows v3
# after
  rm '${dbPath}'
# restart the current (older) build; it builds on v1 and migrates up to v3

import { SchemaVersionTooNewError } from '@core/session/migrations';
function isSchemaVersionTooNew(e: unknown): e is SchemaVersionTooNewError {
  return e instanceof SchemaVersionTooNewError;
}

try {
  migrate(db);
} catch (e) {
  if (e instanceof SchemaVersionTooNewError) {
    // user downgraded; prompt to reset DB or reinstall newer build to export data
    console.error(`DB schema v${e.currentVersion} > build max v${e.highestKnownVersion}; rm '${e.dbPath}'`);
  } else throw e;
}

When it happens

Trigger: migrate() reads SELECT MAX(version) FROM schema_version into current; if current > HIGHEST_KNOWN_VERSION (currently 3), this throws. Distinct from StaleSchemaError — different class, different recovery note (downgrade option mentioned).

Common situations: User ran a newer/canary build, then rolled back to stable; CI test fixtures generated on a newer schema checked into an older branch; a beta build wrote v4 then the user installed the GA build that only knows up to v3.

Related errors

• inherited_schema_missing
• canonical_task_columns_missing
• inspector_activity_schema_missing
• foreign_key_violation
• legacy_table_present

AI-assisted analysis of agalwood/Motrix@1a708ee577 (2026-08-12). Data as JSON: /api/errors/fe45325b71044a94. Report an issue: GitHub.