Sorry you’re running into this — that Alembic “can’t locate revision identified by …” error usually means the DB’s recorded revision doesn’t exist in the migrations that your current Prefect install knows about. A few quick clarifying questions to pick the right path: - Which Prefect version are you on (

prefect version

)? - Which database backend are you using (SQLite default vs. Postgres)? If Postgres, what’s the connection URL? - Is it okay to lose data (i.e., completely wipe the DB), or do you need to preserve history? In the meantime, here are concrete paths that typically fix this. Option A — Start fresh (no data preservation) - If you can discard all data, this is the most reliable/fastest. - Stop the server, then fully remove the database, and start again. This bypasses any Alembic revision mismatch that’s stuck. SQLite (default):

prefect server stop
rm -f ~/.prefect/prefect.db ~/.prefect/prefect.db-wal ~/.prefect/prefect.db-shm
prefect server start

Postgres (drop and recreate the database or schema):

# Example: dropping the whole DB (adjust host/db/user)
psql "<postgresql://user:pass@host:5432/postgres>" -c "DROP DATABASE IF EXISTS prefect;"
psql "<postgresql://user:pass@host:5432/postgres>" -c "CREATE DATABASE prefect;"
# Then start Prefect pointing to that DB
prefect server start

If you prefer to drop the schema only:

psql "<postgresql://user:pass@host:5432/prefect>" -c "DROP SCHEMA public CASCADE; CREATE SCHEMA public;"
prefect server start

Option B — Preserve data (repair alembic_version and run migrations) 1) Stop the server and back up your DB. - SQLite:

prefect server stop
cp ~/.prefect/prefect.db ~/.prefect/prefect.db.bak

- Postgres:

pg_dump "<postgresql://user:pass@host:5432/prefect>" > prefect_backup.sql

2) Inspect the current Alembic revision recorded in your DB. - SQLite:

sqlite3 ~/.prefect/prefect.db "SELECT * FROM alembic_version;"

- Postgres:

psql "<postgresql://user:pass@host:5432/prefect>" -c "SELECT * FROM alembic_version;"

3) If the revision looks wrong (or there are multiple rows), clear it and “stamp” to head. Stamping does NOT run migrations; it just fixes the version marker so Alembic can proceed.

# Clear the version table (adjust for your DB)
sqlite3 ~/.prefect/prefect.db "DELETE FROM alembic_version;"
# or for Postgres use psql to DELETE FROM alembic_version;

# Tell Alembic the DB is at 'head'
prefect server database stamp head

4) Now run the upgrade to apply any needed migrations:

prefect server database upgrade -y
prefect server start

If you still get the same error, try this sequence without manually deleting entries:

prefect server stop
prefect server database stamp head
prefect server database upgrade -y
prefect server start

Common root causes to check - Mixed or changed backends: If you created your DB on SQLite and now point Prefect to Postgres (or vice versa), the revision in

alembic_version

will not match the migrations Prefect is loading. In that case, you must start with a fresh, empty database for the new backend (Option A). - Mixed Prefect versions: The DB was created/migrated with one Prefect version and now you’re running a different version where the referenced revision doesn’t exist. Ensure

prefect version

is what you expect; consider reinstalling to a consistent version across all services. - Locked SQLite files: If SQLite is locked, remove the

~/.prefect/prefect.db-wal

and

~/.prefect/prefect.db-shm

files and try again. - Large DB timeouts: For big Postgres DBs, set a higher timeout before upgrading:

export PREFECT_API_DATABASE_TIMEOUT=600
prefect server database upgrade -y

Verified CLI commands you can use

prefect server database --help
prefect server database reset -y
prefect server database stamp head
prefect server database upgrade -y
prefect server database downgrade -y -r -1

If you share: - the exact Prefect version,

- the full error (including the missing revision id), - your DB backend/URL, - and whether data loss is acceptable, I can tailor the steps precisely (including the safest path to stamp/upgrade vs. wipe).