D1 允许您捕获异常,并记录查询数据库时返回的错误。调试 D1 时,可以使用与调试 Workers 相同的工具。
D1 的 stmt. 和 db. 方法在发生错误时会抛出 Error 对象 ↗。要捕获异常,请记录 e.message 值。
例如,以下代码中的查询包含无效关键字——INSERTZ 而非 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
});
}上述代码抛出以下错误消息:
{
"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 还返回以下错误常量:
| 错误消息 | 描述 | 建议操作 |
|---|---|---|
D1_ERROR |
特定 D1 错误的前缀。 | 请参阅下面的 "List of D1_ERRORs" 了解特定错误的更多详情。 |
D1_EXEC_ERROR |
第 x 行的 Exec 错误:y 错误。 | |
D1_TYPE_ERROR |
当列与值之间的类型不匹配时返回。常见原因是提供 undefined 变量(不支持)而非 null。 |
确保值的类型与列匹配。 |
D1_COLUMN_NOTFOUND |
未找到列。 | 确保您选择的列存在于数据库中。 |
下表列出了 D1_ERROR 的具体实例。
D1_ERROR 列表
D1_ERROR 类型 |
描述 | 建议操作 |
|---|---|---|
No SQL statements detected. |
输入查询不包含任何 SQL 语句。 | App action: 确保查询包含至少一个有效的 SQL 语句。 |
Your account has exceeded D1's maximum account storage limit, please contact Cloudflare to raise your limit |
账户中所有 D1 数据库的总存储已超过账户存储限制。 | App action: 删除未使用的数据库,或将账户升级到付费套餐。 |
Exceeded maximum DB size. |
D1 数据库已超过其存储限制。 | App action: 从数据库中删除数据行,或将数据分片到多个数据库。 |
Your account has exceeded D1's free tier daily row read limit. Upgrade to a paid plan or wait until tomorrow (midnight UTC) to continue. See https://developers.cloudflare.com/d1/platform/limits/ for more details. |
您的账户已达到 D1 免费套餐的每日行读取限额。 | 应用操作:等待限额在世界协调时间午夜重置,或将账户升级到付费套餐。请参阅限制。 |
Your account has exceeded D1's free tier daily row write limit. Upgrade to a paid plan or wait until tomorrow (midnight UTC) to continue. See https://developers.cloudflare.com/d1/platform/limits/ for more details. |
您的账户已达到 D1 免费套餐的每日行写入限额。 | 应用操作:等待限额在世界协调时间午夜重置,或将账户升级到付费套餐。请参阅限制。 |
D1 DB reset because its code was updated. |
Cloudflare 已更新 D1(或底层 Durable Object)的代码,包含 D1 数据库的 Durable Object 正在重启。 | 重试操作。 |
Internal error while starting up D1 DB storage caused object to be reset. |
包含 D1 数据库的 Durable Object 启动失败。 | 重试操作。 |
Network connection lost. |
影响特定 D1 数据库实例的网络错误。每个 D1 数据库都作为独立的 Durable Object 运行。一个数据库发生中断不会影响帐户中的其他数据库。D1 会自动重试只读查询,最多额外重试两次。写入查询不会自动重试。 | 重试此操作。对于写入查询,请使用应用层幂等重试逻辑 — 请参阅重试查询。 |
Replica disconnected from primary. |
只读副本与其主实例之间发生网络错误。 | 重试操作。请参阅上面的 "Retry operation" 说明。 |
Internal error in D1 DB storage caused object to be reset. |
错误导致 D1 数据库重启。 | 重试操作。 |
Cannot resolve D1 DB due to transient issue on remote node. |
查询无法到达包含 D1 数据库的 Durable Object。 | 重试操作。请参阅上面的 "Retry operation" 说明。 |
Can't read from request stream because client disconnected. |
发出了查询请求(例如上传 SQL 查询),但在查询完全执行之前连接已关闭。 | App action: 重试操作,并确保连接保持打开。 |
D1 DB storage operation exceeded timeout which caused object to be reset. |
查询尝试写入大量信息(例如 GB 级),耗时过长。 | App action: 优化查询(使每个查询耗时更短),通过分散负载随时间发送更少请求,或对查询进行分片。 |
D1 DB is overloaded. Requests queued for too long. |
对 D1 数据库的请求排队时间过长,可能是因为请求过多,或排队的请求耗时过长。 | App action: 优化查询(使每个查询耗时更短),通过分散负载随时间发送更少请求,或对查询进行分片。 |
D1 DB is overloaded. Too many requests queued. |
对 D1 数据库的请求队列过长,可能是因为请求过多,或排队的请求耗时过长。 | App action: 优化查询(使每个查询耗时更短),通过分散负载随时间发送更少请求,或对查询进行分片。 |
D1 DB's isolate exceeded its memory limit and was reset. |
查询加载过多内容到内存,导致 D1 数据库崩溃。 | App action: 优化查询(使每个查询耗时更短),通过分散负载随时间发送更少请求,或对查询进行分片。 |
D1 DB exceeded its CPU time limit and was reset. |
查询占用大量 CPU 时间(例如扫描 9 GB 表,或尝试大型导入/导出)。 | App action: 将查询拆分为更小的分片。 |
D1 query result exceeded the maximum response size limit of 50 MB |
查询返回的结果超出了 50 MB 的最大查询结果大小。此限制将于 2026-11-04 起执行。 | 应用操作:只选择所需列,不要使用 SELECT *;或者使用 LIMIT 和 OFFSET 对大型结果集分页。 |
D1 检测只读查询,并在遇到可重试错误导致失败时自动最多重试两次执行这些查询。
D1 确保任何重试尝试不会导致数据库写入,使自动重试不会产生副作用,即使导致修改的查询通过了只读检测。D1 通过在每次查询执行后检查修改来实现这一点,如果重试尝试导致任何写入,查询将被回滚。
使用 wrangler tail 或通过 Cloudflare 仪表板 查看 Worker 的实时日志流。
- 要报告错误或请求功能,请前往 Cloudflare 社区论坛 ↗。
- 要提供反馈,请前往 D1 Discord 频道 ↗。
- 如果您在使用 Wrangler 时遇到问题,请在 Wrangler GitHub 仓库 ↗ 中报告问题。
在任何错误报告中,您应尽可能包含以下内容:
- 数据库的 ID。使用
wrangler d1 list将数据库名称与其 ID 匹配。 - 遇到问题时运行的查询(或查询)。确保编辑任何个人身份信息(PII)。
- 执行查询的 Worker 代码,包括使用 Workers Binding API 对
bind()的任何调用。 - 完整错误文本,包括
error.cause.message的内容。
- 了解如何调试 Workers。
- 了解如何访问 Worker 和 D1 生成的日志。
- 使用
wrangler dev在本地运行 Worker 和 D1,并在部署前调试问题。
D1 绑定方法 — run()、all()、first() 和 batch() — 不接受超时选项或 AbortSignal。D1 绑定客户端没有内置的单次调用超时机制。
只要客户端连接保持打开,Workers 处理传入 HTTP 请求就没有墙钟时间限制 — 请参阅 Workers 限制。如果 D1 数据库暂时无法访问,D1 绑定调用会一直阻塞,直到操作完成、达到内部限制,或 Worker 因客户端断开连接等外部事件而终止。
若要限制 Worker 等待 D1 调用的时间,请使用带计时器的 Promise.race:
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,
]);