Troubleshooting

This page lists the errors you may encounter when working with Netlify Database, what each one means, and how to fix it.

Migration errors

These errors usually surface during a deploy, when Netlify applies your pending migrations to the target database branch.

Migration modified after being applied

Cause

A migration that has already been applied to the target database has had its file contents changed. Netlify tracks each applied migration’s checksum, so editing a migration after it has shipped is detected as drift between what’s stored in the database and what’s in your repository.

migration "<name>" has been modified after being applied

Resolution

Never edit an already-applied migration. Revert your local change so the file matches what was applied, then create a new migration that performs the additional schema change you wanted to make.

If you’ve lost the original contents, netlify database migrations pull downloads the migrations from a remote branch and overwrites your local files with them:

netlify database migrations pull

If the migration was applied incorrectly and you genuinely need to roll it back, write a new corrective migration rather than editing history.

Migration removed after being applied

Cause

A migration that has previously been applied to the target database is no longer present in your repository. As with the previous error, this represents drift between applied state and source-of-truth.

migration "<name>" has been removed after being applied

Resolution

Restore the deleted migration file so the local state matches what was applied. The fastest way is netlify database migrations pull, which pulls all applied migrations from a remote branch back into your local migrations directory:

netlify database migrations pull

If you use version control, you can also recover a deleted file from your Git history (e.g. git revert or git checkout).

If you genuinely want to undo a migration, write a new compensating migration instead.

Out-of-order migration

Cause

You’ve added a new migration whose version prefix is lower than or equal to the highest migration that has already been applied to the database. Netlify won’t silently skip it, because doing so would leave you with a database whose state doesn’t match the files in your project.

migration "<name>" (version <N>) was added out of order: current database version is <M>

Resolution

Rename the offending migration with a higher prefix so it sorts after every already-applied migration.

We recommend using timestamp prefixes (e.g. 20260426143000_add_users.sql) precisely to avoid this — newly created migrations always have a higher prefix than older ones. Using netlify database migrations new handles the prefix for you:

netlify database migrations new --description "add users table"

If the offending migration hasn’t been applied anywhere yet and you’d rather discard it than rename it, netlify database migrations reset deletes any local migrations that haven’t been applied to the target database:

netlify database migrations reset

Migration SQL failed

Cause

A migration ran but the SQL itself failed (syntax error, constraint violation, missing reference, etc.). The underlying database error is included in the message.

error running migrations: <underlying error>

Resolution

Inspect the SQL in the failing migration — the deploy log will include the database’s error message. To iterate locally before pushing again, apply the migration to your local development database with netlify database migrations apply:

netlify database migrations apply

You can also test SQL ad-hoc against the local database with netlify database connect:

netlify database connect --query "SELECT * FROM users LIMIT 1"

Fix the migration on a deploy preview before merging, since a failure on production blocks the deploy from being published.

Migration not found

Cause

Returned by the read endpoint when you ask for a migration by name and either the named migration doesn’t exist on the site, or there is no published deploy yet for the site.

migration "<name>" not found

Resolution

Verify the migration name (filename minus extension) and confirm that the deploy that introduced it has been published. Until a production deploy publishes a migration, it isn’t queryable through the API. You can list applied and pending migrations with netlify database status:

netlify database status

Branch missing for deploy

Cause

You’re applying migrations against a deploy ID, but the deploy hasn’t yet had a database branch created for it.

branch for deploy not found

Resolution

Ensure the deploy is a Netlify deploy preview that successfully created a branch (look for the branch creation step in the deploy log), or trigger a new deploy.

Branch errors

Branch not found

Cause

You’re trying to read, reset, or delete a branch that doesn’t exist for this database.

branch "<branchID>" not found

Resolution

Confirm the branch ID is correct. You can query a specific branch with netlify database status --branch to verify it exists:

netlify database status --branch my-feature-branch

You can also list branches via the REST API or the dashboard.

Parent branch not found

Cause

You called the create-branch endpoint with a parent_branch_id that doesn’t exist.

parent branch <parentBranchID> not found

Resolution

Omit parent_branch_id to fork from production, or pass an ID for a branch that exists.

Source branch not found

Cause

You’re resetting a branch from a source branch that doesn’t exist.

source branch "<sourceBranchID>" not found

Resolution

Check the source branch ID, or omit it to reset from production.

Cannot reset the production branch

Cause

Reset is only available for non-production branches — production is the source of truth and is never re-forked from itself.

cannot reset the production branch

Resolution

If you need to roll production back, restore from a snapshot instead.

Branch limit reached

Cause

Your account has hit the maximum number of active non-production database branches allowed by your plan. Each active deploy preview consumes one branch.

branch limit reached: maximum <N> branches allowed for this account tier

Resolution

Delete branches that are no longer needed (e.g. for closed pull requests), or upgrade your plan. Plan limits are listed on the Billing and usage page.

Invalid branch ID

Cause

The branch ID in the URL couldn’t be decoded — usually a malformed or unencoded path segment.

invalid branch ID

Resolution

Check that branch IDs are URL-encoded correctly when calling the REST API.

Snapshot errors

Invalid branch name

Cause

You called the create-snapshot or restore endpoint with a branch name that doesn’t exist.

invalid branch name

Resolution

Verify the branch name. Omit branch_name to default to production.

Compute settings errors

These apply when configuring auto-scale and sleep on inactivity on a database or branch.

Compute customization requires a higher plan

Cause

Your account is on a tier (Free or Personal) that doesn’t allow customizing compute settings — the default settings are used.

compute customization requires a Pro or higher plan

Resolution

Upgrade to a Pro or higher plan to set custom min/max compute and sleep timeouts.

Database availability errors

Database is disabled

Cause

The database has been disabled — operations on it (queries, branch creation, snapshots, migrations) are blocked until it’s re-enabled.

database is disabled

Resolution

Re-enable the database from the Netlify UI, or contact a Team Owner if you don’t have permission. Confirm the current state with netlify database status:

netlify database status

Database not found

Cause

You’re calling an endpoint for a site that doesn’t have a database provisioned yet.

database not found

Resolution

If you haven’t set Netlify Database up yet, run netlify database init to install @netlify/database, scaffold a starter migration, and verify the database is reachable:

netlify database init

Once @netlify/database is installed, Netlify provisions the database on the next deploy. You can also create one manually from the Netlify UI.

Database limit reached

Cause

Your account has hit the maximum number of databases allowed by your plan.

database limit reached

Resolution

Delete databases you no longer need, or upgrade your plan. Plan limits are listed on the Billing and usage page.

Database feature not available for this account

Cause

Netlify Database isn’t available on your plan — it requires a Credit-based plan.

database feature not available for this account

Resolution

Switch to a Credit-based plan. See Billing and usage for details.

Permission errors

Access denied

Cause

Your role doesn’t grant permission for the operation you’re attempting (e.g. only a Team Owner can delete a database, only Team Owners and Developers can view connection strings).

Access Denied

Resolution

Refer to the permissions table for the role required, and ask a Team Owner to grant it or perform the action on your behalf.

Validation errors

Invalid request body

Cause

The JSON body you sent couldn’t be parsed or didn’t match the expected shape.

invalid request body

Resolution

Check the request body against the REST API reference.