---
title: "Common Troubleshooting"
description: "When working with database schemas, migrations, and connectivity, you may occasionally run into issues such as snapshot collisions, out-of-date migration formats, connection configuration problems,..."
last_updated: "2026-10-12T08:15:22.001931+00:00"
canonical_url: "https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/troubleshooting/common-troubleshooting"
---

## Overview

### About Common Troubleshooting

When working with database schemas, migrations, and connectivity, you may occasionally run into issues such as snapshot collisions, out-of-date migration formats, connection configuration problems, or safety warnings during schema updates. This guide covers how to diagnose and resolve these common scenarios effectively.

> [!NOTE]
> Always ensure your tooling is up-to-date before troubleshooting migration version mismatches.

---

### Migration Conflicts and Outdated Snapshots

#### Conflict Types and Migration Formatting
Migration conflicts typically occur when multiple migration files point to the same parent snapshot, or when your project uses an older version of snapshot formats that need upgrading.

#### Outdated Migration Folders or Non-Latest Snapshots
If your migrations folder or individual snapshots are using an outdated version, you will see a notice indicating that snapshots are not of the latest version or that your folder format is legacy.
* **Fix for legacy folders:** Run `drizzle-kit up`.
* **Fix for version upgrades:** Depending on your dialect, run the appropriate update command to bring your snapshots up to the latest specification (such as upgrading PostgreSQL snapshots or migrating older V4/V5 snapshot schemas).

#### Snapshot Collisions
A snapshot collision happens when two or more distinct snapshot files point to the exact same parent snapshot ID. 
* To check for collisions and malformed files in your migrations directory, run `drizzle-kit check` for your specific database dialect.
* If a collision is detected, review the generated report output to identify which child snapshots share the same parent path, and resolve the conflicting migration branches in your version control history.

---

### Diagnosing Connection and Configuration Issues

#### Configuration and Connection Constraints
Connection issues often arise when required driver parameters are missing, or when using unsupported commands with specific database drivers.

#### Driver-Specific Restrictions and Missing Parameters
Certain drivers have strict limitations regarding which commands (`migrate`, `push`, `pull`, `studio`) they support. If you supply invalid parameters or use an unsupported command, the tool will report an error and list the required configuration parameters.

| Driver / Environment | Unsupported Commands | Required Parameters / Notes |
| :--- | :--- | :--- |
| **Expo SQLite** | `migrate`, `studio`, `pull`, `push` | Follow the specific Expo SQLite setup guide in the documentation. |
| **SQLite Durable Objects** | `migrate`, `studio`, `pull`, `push` | Not supported for these management commands. |
| **D1 HTTP** | *Varies by context* | Requires `accountId`, `databaseId`, and `token`. |

> [!WARNING]
> Attempting to run unsupported commands like `drizzle-kit migrate` or `drizzle-kit studio` with Expo SQLite or SQLite Durable Objects will terminate the process with an error message guiding you to the appropriate plugin or workflow.

---

### Handling Data Loss Warnings and Safety Prompts

#### Understanding Safety Prompts
When pushing schema changes directly to a database, safety checks analyze pending statements to protect existing data (such as dropping tables, removing columns, or changing primary keys).

#### Common Warnings and Safeguards
* **Dropping tables or columns:** If you attempt to drop a table or column that contains existing rows, a warning displays the exact table or column name along with the item count.
* **Not-null columns without defaults:** Adding a `NOT_NULL` column to a table that already contains data without providing a default value will prompt a warning. Depending on the database engine, this may require truncating the table or aborting the operation.
* **Primary key alterations:** Changing or dropping a primary key on a table with existing data can cause statements to fail or leave the table without a primary key.
* **Auto-increment conflicts:** In MySQL and SingleStore, removing a primary key from a table while leaving an `autoincrement` property on a column will trigger an error because auto-increment columns must be defined as a key:
  > *Error:* `There can be only one auto column, and it must be defined as a key. Make sure to remove autoincrement from your table.`

> [!CAUTION]
> Operations that truncate tables or drop populated columns will result in permanent data loss. Always back up your database before confirming destructive schema updates.

## Related

- [Managing Migrations](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/how-to-guides/managing-migrations)
- [Connecting Databases](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/guide/getting-started/connecting-databases)


## Sitemap

See the full [sitemap](https://www.doc0.dev/docs/e1b68fed-3c4e-4c95-b2ba-ebf050f78025/llms.txt) for all pages in this wiki.