Pular para o conteúdo

Debug D1

Atualizado em Ver como Markdown

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:

try {
    // This is an intentional misspelling
    await db.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.
Your account has exceeded D1's maximum account storage limit, please contact Cloudflare to raise your limit. The total storage across all D1 databases in the account has exceeded the account storage limit. App action: Delete unused databases, or upgrade your account to a paid plan.
Exceeded maximum DB size. The D1 database has exceeded its storage limit. App action: Delete data rows from the database, or shard your data into multiple databases.
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.

View logs

View a stream of live logs from your Worker by using wrangler tail or via the Cloudflare dashboard.

Report issues

You should include as much of the following in any bug report:

  • The ID of your database. Use wrangler d1 list to match a database name to its ID.
  • The query (or queries) you ran when you encountered an issue. Ensure you redact any personally identifying information (PII).
  • The Worker code that makes the query, including any calls to bind() using the Workers Binding API.
  • The full error text, including the content of error.cause.message.