agalwood/Motrix · critical · StaleSchemaError

inspector_activity_schema_missing

inspector_activity_schema_missing

Error message

The versioned database schema is incompatible with this build: expected canonical schema objects (task inspector activity and notification tables, constraints, or indexes) are invalid. This unpublished build updates the canonical v1 schema directly, so an existing local development database can have a valid version marker while its substantive tables are stale.

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

What it means

StaleSchemaError reason 'inspector_activity_schema_missing', thrown inside validateCanonicalV3() when hasExactSchemaObjects(db, V3_SCHEMA_OBJECTS) returns false. The v3 inspector activity tables (task_inspector_activity, task_history_events, task_transfer_samples, plus their constraints/indexes) do not EXACTLY match the canonical DDL. Fires post-migration after inherited+task checks passed.

Source

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

function assertCanonicalTaskSchema(
  db: Database.Database,
  objects: readonly { name: string; sql: string }[]
): void {
  if (!hasExactCanonicalTaskSchema(db, objects)) {
    throw new StaleSchemaError(
      'canonical_task_columns_missing',
      (db as unknown as { name: string }).name
    )
  }
}

function validateCanonicalV3(db: Database.Database): void {
  const dbPath = (db as unknown as { name: string }).name
  assertCanonicalInheritedSchema(db)
  assertCanonicalTaskSchema(db, V2_TASK_SCHEMA_OBJECTS)

  if (!hasExactSchemaObjects(db, V3_SCHEMA_OBJECTS)) {
    throw new StaleSchemaError('inspector_activity_schema_missing', dbPath)
  }

  const unexpectedIndexes = [
    'task_inspector_activity',
    'task_history_events',
    'task_transfer_samples',
  ].flatMap((table) =>
    (
      db.prepare(`PRAGMA index_list(${table})`).all() as Array<{
        name: string
        origin: string
      }>
    ).filter((index) => index.origin === 'c')
  )
  const unexpectedTriggers = db
    .prepare(
      `SELECT name FROM sqlite_master
       WHERE type = 'trigger'

View on GitHub (pinned to 1a708ee577)

Solutions

1. Delete the DB and restart — migrate() applies v3 from a clean baseline.
2. If v3 was supposed to run, verify the v3 migration function (v3.up) is in MIGRATIONS and current < 3 in schema_version.
3. Compare each V3_SCHEMA_OBJECTS entry's normalized SQL against sqlite_master to locate the drift.

Example fix

# before: inspector activity tables missing or DDL-drifted
# after
  rm '${dbPath}'
# restart; v3 migration runs and validateCanonicalV3 passes

function isStaleSchemaError(e: unknown): e is StaleSchemaError { return e instanceof StaleSchemaError; }

try {
  migrate(db);
} catch (e) {
  if (e instanceof StaleSchemaError && e.reason === 'inspector_activity_schema_missing') {
    // confirm v3 migration ran; reset DB if needed
  } else throw e;
}

When it happens

Trigger: validateCanonicalV3(db) line 237: hasExactSchemaObjects(db, V3_SCHEMA_OBJECTS) is false because one of the v3 tables' normalized SQL differs from the expected object text — missing column, wrong type, missing FK, etc.

Common situations: DB created before v3 was added running on a v3 build for the first time but v3 migration did not run cleanly; manual edits to the inspector activity tables; a half-applied v3 migration; DDL text drift in a local branch.

Related errors

• inherited_schema_missing
• canonical_task_columns_missing
• foreign_key_violation
• legacy_table_present
• new_tables_missing

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