ERROR database migration_error ai_generated true

alembic.util.exc.CommandError: Can't locate revision identified by 'abc123' / ERROR: migration failed: schema version conflict

ID: database/migration-failed

Also available as: JSON · Markdown
85%Fix Rate
88%Confidence
58Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
16 active — — —

Root Cause

Database migration tool cannot apply a migration due to version conflicts, missing migration files, corrupted migration state, or SQL errors within the migration. The schema_migrations/alembic_version table is out of sync with the actual schema or available migration files.

generic

Workarounds

  1. 87% success Fix the failed migration SQL and re-apply it within a transaction 
    Check the migration tool's error output for the specific SQL error. Fix the migration file. If the migration partially applied, manually inspect the schema (\d+ table_name) and either revert the partial changes or update the migration to be idempotent (IF NOT EXISTS, IF EXISTS). Re-run: alembic upgrade head or equivalent.
  2. 83% success Reconcile the migration state with the actual database schema 
    Compare the current schema (pg_dump --schema-only) with what the migration tool expects. For Alembic: 'alembic current' shows current version, 'alembic history' shows available migrations. Fix any mismatch by creating a corrective migration or using 'alembic stamp <version>' only after verifying the schema actually matches that version.

Dead Ends

Common approaches that don't work:

  1. Manually editing the migration version table to skip failed migrations 75% fail

    Stamping the version table without actually applying the migration leaves the schema in an inconsistent state. The database schema does not match what the migration tool expects, causing cascading failures in subsequent migrations.

  2. Dropping all tables and re-running all migrations from scratch in production 70% fail

    Dropping tables in production destroys all data. This approach is acceptable in development but catastrophic in production environments with live data.

Error Chain

Leads to:
Preceded by:
Frequently confused with: