{"record":{"id":"a781b6ef1badf87f","repo":"agalwood/Motrix","slug":"inspector-activity-schema-missing","errorCode":"inspector_activity_schema_missing","errorMessage":"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.\n\nAction: delete the database file and restart the app to recreate it on the current v1 schema.\n  rm '${dbPath}'","messagePattern":"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\\.\n\nAction: delete the database file and restart the app to recreate it on the current v1 schema\\.\n  rm '(.+?)'","errorType":"exception","errorClass":"StaleSchemaError","httpStatus":null,"severity":"critical","filePath":"src/core/session/migrations/index.ts","lineNumber":238,"sourceCode":"function assertCanonicalTaskSchema(\n  db: Database.Database,\n  objects: readonly { name: string; sql: string }[]\n): void {\n  if (!hasExactCanonicalTaskSchema(db, objects)) {\n    throw new StaleSchemaError(\n      'canonical_task_columns_missing',\n      (db as unknown as { name: string }).name\n    )\n  }\n}\n\nfunction validateCanonicalV3(db: Database.Database): void {\n  const dbPath = (db as unknown as { name: string }).name\n  assertCanonicalInheritedSchema(db)\n  assertCanonicalTaskSchema(db, V2_TASK_SCHEMA_OBJECTS)\n\n  if (!hasExactSchemaObjects(db, V3_SCHEMA_OBJECTS)) {\n    throw new StaleSchemaError('inspector_activity_schema_missing', dbPath)\n  }\n\n  const unexpectedIndexes = [\n    'task_inspector_activity',\n    'task_history_events',\n    'task_transfer_samples',\n  ].flatMap((table) =>\n    (\n      db.prepare(`PRAGMA index_list(${table})`).all() as Array<{\n        name: string\n        origin: string\n      }>\n    ).filter((index) => index.origin === 'c')\n  )\n  const unexpectedTriggers = db\n    .prepare(\n      `SELECT name FROM sqlite_master\n       WHERE type = 'trigger'","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/agalwood/Motrix/blob/1a708ee57746c434e2c67a44bbf0906a976afea4/src/core/session/migrations/index.ts#L220-L256","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Delete the DB and restart — migrate() applies v3 from a clean baseline.","If v3 was supposed to run, verify the v3 migration function (v3.up) is in MIGRATIONS and current < 3 in schema_version.","Compare each V3_SCHEMA_OBJECTS entry's normalized SQL against sqlite_master to locate the drift."],"exampleFix":"# before: inspector activity tables missing or DDL-drifted\n# after\n  rm '${dbPath}'\n# restart; v3 migration runs and validateCanonicalV3 passes","handlingStrategy":"try-catch","validationCode":null,"typeGuard":"function isStaleSchemaError(e: unknown): e is StaleSchemaError { return e instanceof StaleSchemaError; }","tryCatchPattern":"try {\n  migrate(db);\n} catch (e) {\n  if (e instanceof StaleSchemaError && e.reason === 'inspector_activity_schema_missing') {\n    // confirm v3 migration ran; reset DB if needed\n  } else throw e;\n}","preventionTips":["When adding v3 tables in a PR, ensure v3.up is in MIGRATIONS and V3_SCHEMA_OBJECTS matches exactly.","Reset dev DB after pulling changes that touch v3 schema.","Use in-memory DBs in unit tests to avoid cross-test contamination."],"tags":["database","sqlite","migration","schema","v3","inspector-activity","stale-schema"],"backgroundTag":null,"analyzedSha":"1a708ee57746c434e2c67a44bbf0906a976afea4","analyzedAt":"2026-08-12T16:18:09.346Z","schemaVersion":2},"datasetVersion":"2026-08-12T18:17:37.767Z"}