references/d1/gotchas.md
D1 Gotchas & Troubleshooting
Use current documentation to diagnose the failure before changing query or database configuration.
| Symptom or question | What to check |
| --- | --- |
| Missing table, query exception, or constraint error | Debug D1; verify the target binding, environment, and applied migrations |
| Boolean, date, or other binding type mismatch | Workers Binding API type conversion and SQL support |
| Foreign key failure during writes or migrations | Foreign key enforcement and deferral |
| Slow or expensive database, excessive rows read or written, or finding which databases and queries cost the most | Find slow and expensive queries with cf sql query or wrangler d1 insights (API tokens need Account Analytics Read); then indexes and query plans |
| Query duration, statement, storage, or account limits | Current limits |
| Unexpected usage charges or plan assumptions | Pricing; find the databases and queries that cost the most |
| Stale reads after a write | Sessions, bookmarks, and read replication |
| Transient query failures | Retry guidance; check idempotency before retrying writes |
| Import/export failure or unsupported data | Import/export behavior and limitations |
| Local and deployed databases differ | Local development and environment configuration |
Continue to bind untrusted SQL values as described in api.md. Do not treat SQL injection as a recoverable database error or assume retries correct invalid queries.