Debug D1

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"
}

D1 returns the following error constants, in addition to the extended (detailed) error message:

The following table lists specific instances of D1_ERROR.

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 a stream of live logs from your Worker by using wrangler tail or via the Cloudflare dashboard.

• To report bugs or request features, go to the Cloudflare Community Forums ↗︎.
• To give feedback, go to the D1 Discord channel ↗︎.
• If you are having issues with Wrangler, report issues in the Wrangler GitHub repository ↗︎.

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.

• Learn how to debug Workers.
• Understand how to access logs generated from your Worker and D1.
• Use wrangler dev to run your Worker and D1 locally and debug issues before deploying.

D1 binding methods — run(), all(), first(), and batch() — do not accept a timeout option or an AbortSignal. There is no per-call timeout built into the D1 binding client.

Workers have no wall-time limit on incoming HTTP requests while the client connection is open — see Workers limits. If the D1 database is temporarily unreachable, a D1 binding call blocks until the operation completes, an internal limit is reached, or the Worker is terminated by an external event such as the client disconnecting.

To limit how long your Worker waits on a D1 call, use Promise.race with a timer:

const timeout = new Promise((_, reject) =>
  setTimeout(() => reject(new Error('D1 call timed out')), 5000)
);
const result = await Promise.race([
  db.prepare('SELECT 1').first(),
  timeout,
]);

In addition to the D1_ERROR constants in the Error list, D1 returns numeric error codes on certain failures. Use the following table to identify the cause and recommended action.

If you receive error 7429 while your analytics show fast SQL execution times, the error may originate from a server-side platform event rather than your application's workload. The queryBatchTimeMs metric measures only SQL execution time inside the database, not the total time a request spends waiting to reach SQL. Check the Cloudflare System Status ↗︎ page before reducing application concurrency. If the error recurs and you suspect slow or expensive queries are contributing, refer to Find slow and expensive queries to identify the databases and queries using the most resources.

Error 10000 is an authentication error that occurs when the API token does not have the required permission for the endpoint. It is not specific to the export endpoint.

The most common cause for error 10000 during export is using a D1 Read token instead of a D1 Write token. The export operation requires D1 Write permission because it locks the database until the export completes — it is not a read-only operation.

To resolve this:

1. Go to API Tokens in your Cloudflare dashboard. Go to API Tokens ↗
2. Create a new token with D1 Write permission — or check the API reference for the required permission for the specific endpoint you are calling.
3. Use that token for the request.