D1 allows you to capture exceptions and log errors returned when querying a database. To debug D1, you will use the same tools available when debugging Workers.
D1's stmt. and db. methods throw an Error object ↗ whenever an error occurs. To capture exceptions, log the e.message value.
For example, the code below has a query with an invalid keyword - INSERTZ instead of INSERT:
JavaScript
try{
// This is an intentional misspelling
awaitdb.exec("INSERTZ INTO my_table (name, employees) VALUES ()");
}catch(e:any){
console.error({
message:e.message
});
}
The code above throws the following error message:
{
"message":"D1_EXEC_ERROR: Error in line 1: INSERTZ INTO my_table (name, employees) VALUES (): sql error: near \"INSERTZ\": syntax error in INSERTZ INTO my_table (name, employees) VALUES () at offset 0"
}
Error list
D1 returns the following error constants, in addition to the extended (detailed) error message:
Error message
Description
Recommended action
D1_ERROR
Prefix of a specific D1 error.
Refer to "List of D1_ERRORs" below for more detail about your specific error.
D1_EXEC_ERROR
Exec error in line x: y error.
D1_TYPE_ERROR
Returned when there is a mismatch in the type between a column and a value. A common cause is supplying an undefined variable (unsupported) instead of null.
Ensure the type of the value and the column match.
D1_COLUMN_NOTFOUND
Column not found.
Ensure you have selected a column which exists in the database.
The following table lists specific instances of D1_ERROR.
List of D1_ERRORs
D1_ERROR type
Description
Recommended action
No SQL statements detected.
The input query does not contain any SQL statements.
App action: Ensure the query contains at least one valid SQL statement.
D1 DB reset because its code was updated.
Cloudflare has updated the code for D1 (or the underlying Durable Object), and the Durable Object which contains the D1 database is restarting.
Retry the operation.
Internal error while starting up D1 DB storage caused object to be reset.
The Durable Object containing the D1 database is failing to start.
Retry the operation.
Network connection lost.
A network error.
Retry the operation. Refer to the "Retry operation" note above.
Internal error in D1 DB storage caused object to be reset.
An error has caused the D1 database to restart.
Retry the operation.
Cannot resolve D1 DB due to transient issue on remote node.
The query cannot reach the Durable Object containing the D1 database.
Retry the operation. Refer to the "Retry operation" note above.
Can't read from request stream because client disconnected.
A query request was made (e.g. uploading a SQL query), but the connection was closed during the query was fully executed.
App action: Retry the operation, and ensure the connection stays open.
D1 DB storage operation exceeded timeout which caused object to be reset.
A query is trying to write a large amount of information (e.g. GBs), and is taking too long.
App action: Optimize the queries (so that each query takes less time), send fewer requests by spreading the load over time, or shard the queries.
D1 DB is overloaded. Requests queued for too long.
The requests to the D1 database are queued for too long, either because there are too many requests, or the queued requests are taking too long.
App action: Optimize the queries (so that each query takes less time), send fewer requests by spreading the load over time, or shard the queries.
D1 DB is overloaded. Too many requests queued.
The request queue to the D1 database is too long, either because there are too many requests, or the queued requests are taking too long.
App action: Optimize the queries (so that each query takes less time), send fewer requests by spreading the load over time, or shard the queries.
D1 DB's isolate exceeded its memory limit and was reset.
A query loaded too much into memory, causing the D1 database to crash.
App action: Optimize the queries (so that each query takes less time), send fewer requests by spreading the load over time, or shard the queries.
D1 DB exceeded its CPU time limit and was reset.
A query is taking up a lot of CPU time (e.g. scanning over 9 GB table, or attempting a large import/export).
App action: Split the query into smaller shards.
Automatic retries
D1 detects read-only queries and automatically attempts up to two retries to execute those queries in the event of failures with retryable errors.
D1 ensures that any retry attempt does not cause database writes, making the automatic retries safe from side-effects, even if a query causing modifications slips through the read-only detection. D1 achieves this by checking for modifications after every query execution, and if any write occurred due to a retry attempt, the query is rolled back.
