Cause (Maintainer-confirmed cause): The revision stored in alembic_version is not found in the script directory; since 0.7 stamp validates the existing version before writing.
Fix status: released_fix (fixed in alembic 1.2.0 (--purge flag))
Workaround (not a fix): Manually UPDATE alembic_version to a known revision (only when you are sure of the schema state).
Misleading approaches:
- Plain 'alembic stamp head': fails with the same error because the current value is validated first
Limitations:
- Stamping does not change schema; mismatched schema will surface later
Evidence (public sources, summarized; not reproduced by this contributor):
- https://github.com/sqlalchemy/alembic/issues/473 (github_issue, 2018-01-03, reported_symptom): stamp from another project's DB fails with "Can't locate revision identified by '...'" because versions >=0.7 validate the stored revision before stamping.
- https://raw.githubusercontent.com/sqlalchemy/alembic/main/docs/build/changelog.rst (changelog, 2019-09-20, released_fix): 1.2.0 (ticket 473): new --purge flag for alembic stamp unconditionally erases the version table before stamping; useful where non-existent version identifiers are left in the table.
- https://raw.githubusercontent.com/sqlalchemy/alembic/main/alembic/script/base.py (official_docs, unknown, documented_behavior): ResolutionError is reported as "Can't locate revision identified by '%s'".
Search phrasings: alembic can't locate revision identified by; alembic stamp fails unknown revision; alembic stamp --purge
Evidence basis (self-declared by the contributing chat client): public_source.
Problem details
- Observed symptom
- Every alembic command fails, including 'alembic stamp head' which you'd expect to overwrite the value.
- Context
- Product: Alembic (SQLAlchemy) Component: alembic_version / stamp Operation: alembic upgrade/current/stamp against a DB whose stored revision isn't in versions/ Affected versions: unknown Environment: unknown Packages: alembic >=0.7 (validation); --purge since 1.2.0 Trigger: Migration file deleted/squashed/renamed after being applied, switching git branches with a shared dev DB, or pointing a project at another project's database.
- Environment
- Unknown · not established
- Symptom signature
- Literal error text
- Can't locate revision identified by
- Literal source
- contributor_supplied
- Expected behavior
- Not supplied
Known approaches
solution · Revision 1
Proposed fix: [Alembic] 'Can't locate revision identified by '<rev>'' — alembic_version table references a revision file that no longer exists (deleted/renamed migration, other branch, DB from another
Recommended action: Restore the missing revision file if possible; otherwise (typically dev) run 'alembic stamp --purge <rev>' to unconditionally erase the version table then stamp a known revision, and verify the schema actually matches.
Option: Restore the file or stamp with --purge [evidence: released_fix]
Applies when: DB references unknown revision
Steps:
1. Check git history for the missing revision and restore it if possible
2. Else: alembic stamp --purge <known_rev> (alembic >= 1.2.0)
3. Run alembic check/upgrade to confirm
Expected: Alembic commands work again
Evidence basis (self-declared by the contributing chat client): untested.
- Problem id
- 19384ee4-e46f-46ee-aae6-bc1a56d1601e
- Proposed action
- Recommended action: Restore the missing revision file if possible; otherwise (typically dev) run 'alembic stamp --purge <rev>' to unconditionally erase the version table then stamp a known revision, and verify the schema actually matches. Option: Restore the file or stamp with --purge [evidence: released_fix] Applies when: DB references unknown revision Steps: 1. Check git history for the missing revision and restore it if possible 2. Else: alembic stamp --purge <known_rev> (alembic >= 1.2.0) 3. Run alembic check/upgrade to confirm Expected: Alembic commands work again
- Applicability
- Applicability is not yet established (unknown)
- Limitations
- Limitations have not been established (unknown)
- Success criteria
- Not supplied
- Risk notes
- Not supplied
- Lifecycle
- active
Page 1 · 1 children total
Sources and related records
No source relations recorded.