Fix CommandError: alembic.util.exc.CommandError: Target database is not up to date in Flask

This error occurs when Alembic detects that the database schema is out of sync with the migration history. You typically hit it when running flask db migrate before applying pending migrations. Fix it by running flask db upgrade first to bring the database up to date, then generate new migrations.

Reading the Stack Trace

Here's what each line means:

• File "/app/venv/lib/python3.12/site-packages/flask_migrate/cli.py", line 134, in migrate: The flask db migrate command was invoked to generate a new migration script.
• File "/app/venv/lib/python3.12/site-packages/alembic/command.py", line 225, in revision: Alembic tries to create a new revision but first checks that all existing migrations have been applied.
• alembic.util.exc.CommandError: Target database is not up to date.: The database version is behind the latest migration, so Alembic refuses to generate a new migration to avoid creating a conflicting revision.

Common Causes

# Ran 'flask db migrate' without first running 'flask db upgrade'
$ flask db migrate -m "add email column"
# ERROR: Target database is not up to date

# Manual SQL: ALTER TABLE user ADD COLUMN phone VARCHAR(20);
# Now the DB doesn't match the Alembic version table

# Deleted migrations/versions/abc123_add_users.py
# But alembic_version table still references 'abc123'

The Fix

Run flask db upgrade first to apply all pending migrations and bring the database schema in sync with the Alembic version history. Then flask db migrate will succeed because it is generating from the current state.

$ flask db migrate -m "add email column"
# alembic.util.exc.CommandError: Target database is not up to date.

$ flask db upgrade
# INFO [alembic.runtime.migration] Running upgrade abc123 -> def456
$ flask db migrate -m "add email column"
# INFO [alembic.autogenerate.compare] Detected added column 'user.email'

Testing the Fix

import pytest
import subprocess
from app import create_app, db

@pytest.fixture
def app():
    app = create_app()
    app.config['TESTING'] = True
    app.config['SQLALCHEMY_DATABASE_URI'] = 'sqlite:///:memory:'
    return app

def test_migrations_apply_cleanly(app):
    with app.app_context():
        from flask_migrate import upgrade
        upgrade()
        # If no exception, all migrations applied successfully

def test_no_pending_migrations(app):
    with app.app_context():
        from flask_migrate import upgrade, migrate
        upgrade()
        # migrate() should produce no changes if models match
        from alembic.autogenerate import compare_metadata
        from flask_migrate import Migrate
        # Verify schema is in sync

Run your tests:

pytest tests/ -v

Pushing Through CI/CD

git checkout -b fix/flask-database-migration-sync,git add migrations/,git commit -m "fix: apply pending migrations before generating new ones",git push origin fix/flask-database-migration-sync

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
          cache: 'pip'
      - run: pip install -r requirements.txt
      - run: flask db upgrade
      - run: pytest tests/ -v --tb=short
      - run: flake8 app/

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

pip install bugstack

import bugstack

bugstack.init(api_key=os.environ["BUGSTACK_API_KEY"])

Deploying the Fix (Manual Path)

1. Run flask db upgrade locally to apply all pending migrations.
2. Open a pull request with any new migration files.
3. Wait for CI checks including migration tests to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and run flask db upgrade in staging and production as part of the deploy pipeline.

Frequently Asked Questions