Error: relation 'supabase_migrations.schema_migrations' does not exist

[supabase-search[bot]]

This is a copy of a troubleshooting article on Supabase's docs site. It may be missing some details from the original. View the original article.

If you are observing the error relation "supabase_migrations.schema_migrations" does not exist in your Postgres logs, it is typically caused by the Supabase dashboard polling for migration history.

Why Does This Happen?
The Supabase dashboard performs background queries to retrieve migration data from a table that is managed specifically by the Supabase CLI. If you are using a custom migration tool, a manual setup, or have not yet deployed migrations via the CLI, this table will not exist, causing the logs to report this error.

How to Resolve:

• Ignore the error: If you are not using the Supabase CLI to manage your database migrations, this error is a harmless side effect of dashboard polling and can be safely ignored.
• Initialize the migration metadata: If you manage your database with the Supabase CLI, running supabase db push will create the supabase_migrations schema and schema_migrations table as part of applying your local migrations. Be aware that this command may also apply any pending migration files to your database, so only run it if that's your intended workflow.

[yakubka]

This error appears in the Postgres logs when the Supabase dashboard polls for migration history and the supabase_migrations schema has not been initialized. It is a dashboard polling artifact and does not mean your migrations are broken.

It happens most often in three situations: (1) a project that was created before the migration tracking schema was introduced, (2) a self-hosted instance where the initial migration setup step was skipped, or (3) a project restored from a pg_dump that did not include the supabase_migrations schema.

To initialize the schema:

CREATE SCHEMA IF NOT EXISTS supabase_migrations;

CREATE TABLE IF NOT EXISTS supabase_migrations.schema_migrations (
version text PRIMARY KEY,
statements text[],
name text
);

After creating the table the polling error disappears from the logs. If you are using the Supabase CLI, running supabase db push against a linked project also creates this schema automatically.