This error means Phoenix's database migration is incomplete or corrupted ("dirty state"). The recommended fix is to use the Alembic CLI from the src/phoenix/db directory to revert partial migrations and run alembic stamp to reset the migration state, then restart Phoenix. If you can't find src/phoenix/db (e.g., when running from a container), you may need to clone the Phoenix repo locally to access it, or run Alembic from the installed package path. This issue often occurs after an upgrade, downgrade, or if the database is shared or manually altered. If you can't afford to lose data, manual intervention is required; otherwise, deleting the database and starting fresh is the simplest fix. Using a dedicated, fresh database for Phoenix is highly recommended to avoid such conflicts.
If you need to run Alembic manually, see the discussion and instructions in these sources. If you need step-by-step guidance for your specific setup (Kubernetes, Docker, etc.), let me know.
Sources:
- <https://github.com/Arize-ai/phoenix/issues/3246|Phoenix migration troubleshooting and Alembic usage>
- <https://arize-ai.slack.com/archives/C04R3GXC8HK/p1720689418.425939|Slack support thread: database dirty state and manual migration>
