Troubleshooting

This page is for diagnosing mismatches between local artifacts, generated code, and the real database state.

Data disappeared after a migration

This usually means either a destructive warning was accepted or a SQLite rebuild copied only compatible scalar columns.

What to inspect:

• warnings.txt in the drafted migration directory
• dart run comon_orm migrate status
• _comon_orm_migrations history, especially before_schema, after_schema, and rebuild_required

Recovery path:

1. stop applying new migrations
2. inspect whether the migration accepted warnings or performed a rebuild
3. decide between a forward fix, restore from backup, or rollback after review

checksum-mismatch

The migration artifact on disk no longer matches what the database recorded.

Stop before applying anything new. Restore the checked-in artifact or create a new forward migration instead of mutating old migration directories.

Typical symptom shape:

status: checksum-mismatch
migration: 20260318_add_post_status

Generated client compiles but runtime fails on missing tables

generate emits code. It does not apply schema changes to a real database.

Use one of these paths instead:

• reviewed CLI migrations for shared PostgreSQL or shared SQLite
• explicit local setup or bootstrap for disposable local databases
• SqliteFlutterMigrator before opening Flutter SQLite when local data must be upgraded in place

Typical symptom shape:

DatabaseException(no such table: users)

local-artifacts-unavailable

This appears on web targets when status flows try to inspect file-backed migration directories.

That is expected. Browser targets should use the device-local Flutter SQLite upgrade path, while shared-database rollout should run in a VM or server environment.

local-migration-not-applied

This means a migration directory exists locally but the database has not recorded it yet.

What to do:

1. confirm the target environment is the one you intended to inspect
2. inspect _comon_orm_migrations to see the recorded end state
3. if the local migration is the next reviewed change for that environment, run migrate deploy

SQLite rebuild warnings

SQLite sometimes needs recreate-copy-swap flows instead of in-place DDL.

That is why warnings may mention rebuilds when you:

• change relation ownership
• change certain native or scalar storage types
• rename or reshape columns in ways SQLite cannot express safely in place

Treat rebuild warnings as a review step. Verify which columns are copied and whether custom local migration code is required.

Fast diagnosis order

1. run migrate status
2. inspect warnings.txt
3. inspect _comon_orm_migrations
4. compare before.prisma and after.prisma
5. decide between forward fix, rollback, reset, or local app-side upgrade code

Continue with

• CLI commands for exact command usage
• Rollback and recovery for recovery strategy
• Flutter local SQLite when the problem is device-local upgrade code rather than shared-database rollout