agalwood/Motrix · critical · StaleSchemaError

inherited_schema_missing

inherited_schema_missing

Error message

The versioned database schema is incompatible with this build: expected canonical schema-version, plugin-state, and transfer tables, columns, constraints, primary keys, indexes, and trigger policy 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 with reason 'inherited_schema_missing', thrown by assertCanonicalInheritedSchema() when the canonical schema_version + plugin-state + transfer tables' DDL, columns, constraints, PK order, indexes, and trigger policy do not EXACTLY match the expected INHERITED_SCHEMA_OBJECTS. This unpublished build edits the canonical v1 schema in place, so the version marker can be valid while the tables are stale.

Source

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

             type = 'trigger'
             OR (type = 'index' AND sql IS NOT NULL)
           )`
      )
      .all(...tables).length === 0
  )
}

function hasExactCanonicalInheritedSchema(db: Database.Database): boolean {
  if (!hasExactSchemaObjects(db, INHERITED_SCHEMA_OBJECTS)) {
    return false
  }

  return hasNoExplicitIndexesOrTriggers(db, INHERITED_TABLES)
}

function assertCanonicalInheritedSchema(db: Database.Database): void {
  if (!hasExactCanonicalInheritedSchema(db)) {
    throw new StaleSchemaError(
      'inherited_schema_missing',
      (db as unknown as { name: string }).name
    )
  }
}

function assertCanonicalSchemaVersion(db: Database.Database): void {
  if (
    !hasExactSchemaObjects(db, SCHEMA_VERSION_OBJECTS) ||
    !hasNoExplicitIndexesOrTriggers(db, ['schema_version'])
  ) {
    throw new StaleSchemaError(
      'inherited_schema_missing',
      (db as unknown as { name: string }).name
    )
  }
}

View on GitHub (pinned to 1a708ee577)

Solutions

1. Delete the dev database file (path is in dbPath in the message) and restart the app to recreate on the current v1 schema.
2. If you need the data, export it first, then delete and re-import on the fresh schema.
3. Avoid hand-editing the schema; if you ALTER during debugging, drop and recreate the DB before the next run.

Example fix

# before: stale dev DB causing throw
# after
  rm '/path/to/session.db'
# restart the app — migrate() will build the current v1 schema from scratch

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

try {
  migrate(db);
} catch (e) {
  if (e instanceof StaleSchemaError && e.reason === 'inherited_schema_missing') {
    // dev-only: prompt user to reset DB; in CI fail fast
    console.error(`Reset required: rm '${e.dbPath}'`);
  } else throw e;
}

When it happens

Trigger: assertCanonicalInheritedSchema(db) returns false because hasExactSchemaObjects(db, INHERITED_SCHEMA_OBJECTS) fails OR hasNoExplicitIndexesOrTriggers(db, INHERITED_TABLES) finds extra triggers/indexes. Called from validateCanonicalV3 (post-migration, line 234) and from Guard B (line 388).

Common situations: Local dev DB from an older PR that created the inherited tables with a slightly different DDL (extra column, different PK order, modified CHECK); a manual ALTER TABLE during debugging that left an extra trigger; an older build that created an explicit index on a table this build expects to have none.

Related errors

• canonical_task_columns_missing
• inspector_activity_schema_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/6a1099ed0a493038. Report an issue: GitHub.