Troubleshooting Prisma Migration Errors

Troubleshooting Prisma Migration Errors

Common Prisma migration issues encountered when upgrading or downgrading LiteLLM proxy versions, and how to fix them.

For a full guide on safely reverting your LiteLLM version, see the Safe Rollback Guide.

How Prisma Migrations Work in LiteLLM

• LiteLLM uses Prisma to manage its PostgreSQL database schema.
• Migration history is tracked in the _prisma_migrations table in your database.
• When LiteLLM starts, it runs prisma migrate deploy to apply any new migrations.
• Upgrading LiteLLM applies all migrations added since your last applied version.

Common Errors

1. relation "X" does not exist

Example error:

ERROR: relation "LiteLLM_DeletedTeamTable" does not exist
Migration: 20260116142756_update_deleted_keys_teams_table_routing_settings

Cause: This typically happens after a version rollback. The _prisma_migrations table still records migrations from the newer version as "applied," but the underlying database tables were modified, dropped, or never fully created.

How to fix:

Step 1 — Delete the failed migration entry and restart

Remove the problematic migration from the history so it can be re-applied:

-- View recent migrations
SELECT migration_name, finished_at, rolled_back_at, logs
FROM "_prisma_migrations"
ORDER BY started_at DESC
LIMIT 10;

-- Delete the failed migration entry
DELETE FROM "_prisma_migrations"
WHERE migration_name = '<failed_migration_name>';

After deleting the entry, restart LiteLLM — it will re-apply the migration on startup.

Step 2 — If that doesn't work, use prisma db push

If deleting the migration entry and restarting doesn't resolve the issue, sync the schema directly:

Warning: prisma db push can cause data loss if the Prisma schema removes columns or tables that exist in your database. Only use this as a last resort and ensure you have a database backup first.

DATABASE_URL="<your_database_url>" prisma db push

This bypasses migration history and forces the database schema to match the Prisma schema.

2. New migrations cannot be applied before the error is recovered from

Cause: A previous migration failed (recorded with an error in _prisma_migrations), and Prisma refuses to apply any new migrations until the failure is resolved.

How to fix:

1. Find the failed migration:

SELECT migration_name, finished_at, rolled_back_at, logs
FROM "_prisma_migrations"
WHERE finished_at IS NULL OR rolled_back_at IS NOT NULL
ORDER BY started_at DESC;

2. Delete the failed entry and restart LiteLLM:

DELETE FROM "_prisma_migrations"
WHERE migration_name = '<failed_migration_name>';

3. If that doesn't work, use prisma db push (see warning above — back up your database first):

DATABASE_URL="<your_database_url>" prisma db push

3. Migration state mismatch after version rollback

Cause: You upgraded to version X (new migrations applied), rolled back to version Y, then upgraded again. The _prisma_migrations table has stale entries for migrations that were partially applied or correspond to a schema state that no longer exists.

Fix:

1. Inspect the migration table for problematic entries:

SELECT migration_name, started_at, finished_at, rolled_back_at, logs
FROM "_prisma_migrations"
ORDER BY started_at DESC
LIMIT 20;

2. For each migration that shouldn't be there (i.e., from the version you rolled back from), delete the entry:

   DELETE FROM "_prisma_migrations" WHERE migration_name = '<migration_name>';
   

3. Restart LiteLLM to re-run migrations.

4. If that doesn't work, use prisma db push (see warning above — back up your database first):

DATABASE_URL="<your_database_url>" prisma db push