DuckDB 通过广泛的测试套件进行了彻底的测试。然而，错误仍然可能发生，有时会导致崩溃。本页包含有关如何排查 DuckDB 崩溃的实用信息。

崩溃类型

主要有以下几种崩溃类型：

• 终止信号：进程因 SIGSEGV（段错误）、SIGABRT 等而停止：这些情况绝不应该发生。请提交问题。

• 内部错误：操作可能导致Internal Error（内部错误），例如：

  INTERNAL Error:
  Attempted to access index 3 within vector of size 3
  

  遇到内部错误后，DuckDB 会进入受限模式，任何进一步的操作都将导致以下错误消息：

  FATAL Error:
  Failed: database has been invalidated because of a previous fatal error.
  The database must be restarted prior to being used again.
  

• 内存不足错误：DuckDB 崩溃也可能是操作系统终止进程的症状。例如，许多 Linux 发行版运行 OOM reaper 或 OOM killer 进程，它会终止进程以释放内存，从而防止操作系统内存耗尽。如果您的 DuckDB 会话被 OOM reaper 终止，请查阅“OOM 错误”页面。

数据恢复

如果您的 DuckDB 会话在崩溃之前正在写入持久数据库文件，那么在数据库旁边可能有一个名为 database_filename.wal 的 WAL（预写日志）文件。要从 WAL 文件恢复数据，只需在持久数据库上启动新的 DuckDB 会话。DuckDB 将重放预写日志并执行检查点操作，将数据库恢复到崩溃之前的状态。

故障排除崩溃

使用最新的稳定版和预览版

DuckDB 持续改进，因此您遇到的错误可能已在代码库中修复。首先，尝试更新到最新的稳定版。如果这不能解决问题，请尝试使用预览版（也称为“夜间构建版”）。

如果您想在代码库中应用了开放拉取请求的情况下使用 DuckDB，您可以尝试从源代码构建。

搜索现有问题

导致崩溃的错误可能已经有人报告了。请在 GitHub 问题跟踪器中搜索错误消息，查看可能相关的问题。DuckDB 有一个庞大的社区，可能有一些变通方法的建议。

禁用查询优化器

某些崩溃是由 DuckDB 的查询优化器组件引起的。要确定优化器是否导致崩溃，请尝试将其关闭并重新运行查询：

PRAGMA disable_optimizer;

如果查询成功完成，则崩溃是由一个或多个优化器规则引起的。要查明导致崩溃的具体规则，您可以尝试选择性地禁用优化器规则。这样，您的查询仍然可以从其余的优化器规则中受益。

尝试隔离问题

某些问题是由不同组件和扩展之间的相互作用引起的，或者特定于某些平台或客户端语言。您通常可以将问题隔离到一个更小的问题。

在纯 SQL 中复现

问题也可能由于客户端库的差异而发生。要了解是否是这种情况，请尝试使用DuckDB CLI 客户端通过纯 SQL 查询来复现问题。如果您无法在命令行客户端中复现问题，则可能与客户端库有关。

不同的硬件设置

根据我们的经验，一些崩溃是由于硬件故障（硬盘过热、CPU 超频等）造成的。因此，值得尝试在另一台计算机上运行相同的工作负载。

分解查询

尝试将查询分解为多个更小的查询是一个好主意，每个查询都使用单独的 DuckDB 扩展和 SQL 特性。

例如，如果您有一个查询针对 AWS S3 存储桶中的数据集并对其执行两次连接，请尝试将其重写为一系列较小的步骤，如下所示。手动下载数据集文件并将其加载到 DuckDB 中。然后分别执行第一次和第二次连接。如果多步骤方法在某个步骤仍然出现崩溃，那么触发崩溃的查询是创建最小可复现示例的良好基础。如果多步骤方法有效且多步骤过程不再崩溃，请尝试重构原始查询并观察是哪个步骤重新引入了错误。在这两种情况下，您都将更好地理解问题的原因，并且可能还会立即获得一个可用的变通方法。无论如何，请考虑提交一个问题并附上您的发现。

提交问题

如果您在 DuckDB 中发现了崩溃，请考虑在我们的 GitHub 问题跟踪器中提交一个问题，并附上最小可复现示例。