跳转到内容
搜索文档
↵选择
↑↓导航
ESC关闭

调试 D1

最后更新 查看 MarkdownAgent 设置

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 还返回以下错误常量：

Error message Description Recommended action
D1_ERROR 特定 D1 错误的前缀。 请参阅下面的 "List of D1_ERRORs" 了解特定错误的更多详情。
D1_EXEC_ERROR 第 x 行的 Exec 错误：y 错误。
D1_TYPE_ERROR 当列与值之间的类型不匹配时返回。常见原因是提供 undefined 变量（不支持）而非 null。 确保值的类型与列匹配。
D1_COLUMN_NOTFOUND 未找到列。 确保您选择的列存在于数据库中。

下表列出了 D1_ERROR 的具体实例。

List of D1_ERRORs

D1_ERROR type Description Recommended action
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: 从数据库中删除数据行，或将数据分片到多个数据库。
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. 网络错误。 重试操作。请参阅上面的 "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 检测只读查询，并在遇到可重试错误导致失败时自动最多重试两次执行这些查询。

D1 确保任何重试尝试不会导致数据库写入，使自动重试不会产生副作用，即使导致修改的查询通过了只读检测。D1 通过在每次查询执行后检查修改来实现这一点，如果重试尝试导致任何写入，查询将被回滚。

查看日志

使用 wrangler tail 或通过 Cloudflare 仪表板 查看 Worker 的实时日志流。

报告问题

在任何错误报告中，您应尽可能包含以下内容：

  • 数据库的 ID。使用 wrangler d1 list 将数据库名称与其 ID 匹配。
  • 遇到问题时运行的查询（或查询）。确保编辑任何个人身份信息（PII）。
  • 执行查询的 Worker 代码，包括使用 Workers Binding API 对 bind() 的任何调用。
  • 完整错误文本，包括 error.cause.message 的内容。

相关资源

这篇文档对您有帮助吗？