Alembic Can’t Locate Revision Identified By | Fix Error

What This Alembic Error Means

This message comes from Alembic when it tries to load a migration revision id from your database or from a command line target, and that revision does not exist in the current migration scripts. Alembic keeps track of schema changes through small Python files in the versions folder and a table named alembic_version inside the database.

Each migration file has a string id such as 3f2a9e8c4a1b, plus a reference to the previous revision through down_revision. When you run alembic upgrade head, Alembic reads the current id from alembic_version, walks the revision graph, and applies the next steps. If one of the referenced ids is missing, you see the familiar line “alembic can’t locate revision identified by ‘…’”. That short model helps when the next schema change lands.

This error does not mean Alembic is broken. It means the recorded history in the database and the migration files no longer match. That mismatch can come from deleted files, branch merges, copied databases, or changes to the migration folder path.

Main Causes Of Alembic Can’t Locate Revision Identified By

The same message appears in many projects, yet the root cause usually falls into a short list. Once you understand these patterns you can pick the safest fix for your case.

• Deleted migration file — A migration file was removed manually from alembic/versions, but its id still sits in the alembic_version table.
• Database copied from another branch — Someone copied a database that already ran newer migrations, while the code checkout still has an older migration history.
• Branch-specific migrations — A teammate added migrations on a feature branch and merged code without applying those migrations on every database.
• Wrong Alembic configuration — The script_location points to the wrong folder, so Alembic loads a different set of versions than the one used to create the database.
• Manual edits to alembic_version — Someone changed the version id in the table without creating a matching migration file.

Most real cases match one of these scenarios. Online discussions and answers about this error almost always trace back to a missing migration file or a mismatched alembic_version entry in the database.

Quick Checks Before You Touch The Database

Before you drop tables or change ids by hand, take a short pass through a few checks. This confirms what Alembic expects and helps you avoid extra damage.

1. Read the exact revision id — Copy the full value from the error message, including every digit. You will use it in searches.
2. Search in the versions folder — Look in alembic/versions for any file that contains that revision id string. If none of the filenames or contents mention it, the file is gone.
3. Inspect the alembic_version table — Open a database shell and run SELECT * FROM alembic_version;. Note the version_num value and check whether it matches an existing migration id.
4. Run alembic history — From the project root, run alembic history. This shows the known revisions in order and reveals gaps or heads that no longer match the database.
5. Confirm the script_location — Open alembic.ini or your custom config and confirm that script_location points to the same migrations folder you just inspected.

If all checks point to a missing migration file, the problem is clear. If the file exists but Alembic still raises “alembic can’t locate revision identified by …”, you likely have multiple migration directories or an older virtualenv using different settings.

Safe Ways To Fix The Missing Revision Problem

The right repair method depends on how much data you care about and whether the database is shared. A local test database can be reset without concern, while a production database must keep its history and content.

If you work on a shared service, agree on a small playbook for this error. Decide when it is safe to reset a database, who takes care of backups, and how to record any manual steps you run during a fix. That avoids hidden changes that confuse teammates in the next release.

Restore The Lost Migration File

The cleanest fix is to bring back the migration file that the database expects. In many cases that file still exists in version control, a backup, or the recycle bin.

• Recover from version control — Check the Git history or other source control for a commit that still contains the missing migration under alembic/versions. Restore that file into the folder.
• Recover from trash — If you deleted the file on your machine, look in the trash or recycle bin and move it back to the versions directory.
• Avoid recreating by hand — Writing a new file with the same id but different content can confuse later upgrades. Use the exact original script when you can.

Once the correct file is back in place, run alembic upgrade head again. In many reported cases the error disappears as soon as the file returns to the expected path.

Align alembic_version With The Latest Valid Revision

When the original migration file is truly lost yet the schema state matches a slightly older revision, you can point alembic_version at that known id. This keeps your data and tells Alembic to resume from the nearest stable point.

1. Pick the target revision — Choose a revision id that still has a file under alembic/versions and that matches the real structure of the database.
2. Backup the database first — Create a dump or snapshot so you can roll back if anything goes wrong.
3. Update the version table — Run a statement such as UPDATE alembic_version SET version_num='chosen_id'; with a real id string.
4. Run alembic upgrade head — Let Alembic apply any migrations that come after the chosen revision.

Developers often use this approach when the database came from a branch that no longer exists or when the latest migration only added objects that can be recreated in a new script.

Reset The Version Table In A Throwaway Database

On a local development database you sometimes just want to start fresh. The error appears, you have no data to keep, and a clean run of all migrations is fine.

• Drop the alembic_version table — In many guides the fix is to run DROP TABLE alembic_version; or delete rows from it. This tells Alembic that no migrations ran yet.
• Recreate the schema from scratch — Run the full chain with alembic upgrade head, or drop the entire database and create a new one before the upgrade.
• Limit this to noncritical data — Use this method only for local or disposable databases where data loss is acceptable.

This reset removes the old history link and lets Alembic rebuild the schema based on the current migration scripts alone.

Use alembic stamp When History Exists But Does Not Match

Sometimes the database was created manually or through another project that shared the same models. The schema matches a later revision while the migration history does not. In that case the alembic stamp command helps align recorded history with current state.

1. Inspect the schema — Confirm that the live database structure matches a known revision in your migration history.
2. Run alembic stamp — Execute a command such as alembic stamp 3f2a9e8c4a1b using the id that matches the real schema.
3. Upgrade to head — Run alembic upgrade head so newer migrations apply cleanly on top of that stamped state.

This command does not change tables. It only updates alembic_version, which clears this Alembic revision lookup error when the stamped id matches a valid file.

Handling Alembic Can’t Find Revision Identifier Errors In Teams

Shared projects bring extra ways to reach this error. Different developers may create migrations on separate branches, apply them in different orders, or run partial upgrades. A little process around Alembic keeps the history chain stable.

• Keep migrations under version control — Never create or remove migration files outside the same commits that adjust models. Review pull requests so that schema changes and migration files stay in sync.
• Avoid manual edits to revision ids — Let Alembic create ids and down_revision links. Editing those strings by hand can form graphs that no longer match the real database state.
• Run migrations after pulling — Make it a habit to run alembic upgrade head or the project wrapper command after each pull from the main branch.
• Use merge migrations for branches — When two branches each add migrations on top of the same base, create an explicit merge revision instead of dropping files from one side.

When every teammate follows the same steps, the chance of hitting this Alembic revision lookup error drops sharply. If it still appears, you can track down which branch or database copy introduced the mismatch.

Preventing This Error During Daily Development

Once you clear the current failure you likely want to avoid seeing it again. A few habits around Alembic and your database keep the migration graph healthy during daily work.

Some teams even add a short note to every pull request that changes models, pointing to the related migration ids. That single line in code review makes it clear which databases may need extra care so the “alembic can’t locate revision identified by …” message stays rare for the team.

• Do not delete migration files casually — Treat files in alembic/versions as part of the schema history. Remove them only during rare, planned cleanups with full backups.
• Name migrations clearly — Use descriptive slugs in migration filenames so you can match ids to real changes later when you read logs or compare histories.
• Keep a separate database per project — Point each project and each developer at its own database, rather than reusing one instance with mixed histories.
• Automate schema checks — Add a small script or pipeline step that runs alembic check or alembic history on new branches to catch gaps early.
• Document the upgrade command — In the project README, show the exact alembic upgrade or project command that teammates should run after syncing code.

The error message “alembic can’t locate revision identified by …” may look alarming the first time you see it. Once you understand that it simply points to a mismatch between the database and the migration files, it turns into a manageable maintenance task rather than a blocker.

Send us your feedbackTell us what you thought about this post

Name * Email *

Your comment *

Quick check — what is …? *

Send feedback