7.3 常见陷阱与报错解码
7.3 常见陷阱与报错解码
本节摘要：报错信息是引擎在尽量说人话，陷阱则是它不说的那部分。本节前半张是高频报错解码表——每条配原因与解法；后半把前六章散落的静默陷阱收成清单。目标：遇到问题时三十秒内对上号，而不是每次重新搜索。
报错也分站点
DuckDB 的报错带类型前缀，前缀本身就完成了第一层分流：Binder Error 是名字层面的问题（列、表、函数名没对上），Conversion Error 是类型转换失败，Out of Memory Error 是内存上限触顶，IO Error 是文件与锁的问题，Catalog Error 是对象不存在（常与没加载的扩展有关）。拿到报错先认前缀，再去读正文——正文通常给了出错位置和候选名，比想象中友好。
高频报错解码表
下面六条覆盖日常绝大多数报错。读法：先看现象，对上自己那条，再看原因列——多数时候原因列已经剧透了解法。
| 报错（前缀与关键句） | 真实原因 | 解法 |
|---|---|---|
| Binder Error: Column "xxx" not found | 列名大小写、别名作用域（WHERE 里用了 SELECT 的别名）、或 JOIN 后两个表有同名列没加前缀 | 用 DESCRIBE 看真实列名；WHERE 里写原始列；同名列带表前缀 |
| Conversion Error: Could not convert string | CSV 嗅探把列读成了窄类型，脏值转换失败 | 嗅探降级为 VARCHAR 后显式 CAST，或指定列类型读入 |
| Out of Memory Error | memory_limit 触顶且操作不可溢出（少见），或并发会话叠加超限 | 查计划找内存大头；单会话内减并发；按 7.1 调整 memory_limit |
| IO Error: Could not set lock on file | 库文件被另一个进程以写模式打开——文件锁是单写者的 | 找到占用的进程关掉；或本会话改只读打开 |
| Catalog Error: Function ... not found | 用到了扩展里的函数但扩展没加载 | LOAD 对应扩展（第6.1节），对象存储场景先 LOAD httpfs |
| Constraint Error: NOT NULL | 建表时声明了非空约束，写入数据有空值 | 先查空值来源；分析场景多数约束不必声明 |
文件锁那条值得多说一句，它是嵌入式架构新手最懵的报错：没有服务端，"谁在占用"只能自己排查。日常预防的办法是约定——同一份库文件，同时只有一个写者；其他人只读模式打开。第2.3节的事务模型决定了这是硬约束，不是参数能放宽的。
Conversion Error 那条则是静默陷阱的"好结局"——它至少报错了。接下来看那些不报错的。
静默陷阱清单：引擎不说话，结果在说谎
比报错贵得多的，是下面这些不报错的问题。每一条都在前文出现过，这里收拢成清单，使用方式是交付前逐条过：
一、类型静默降级。嗅探把带脏值的金额列读成 VARCHAR，比较不报错、聚合走字符串序——max(amount) 返回"999.5"而不是九百九十九块五。第5.2节主线案例亲身踩过，解法是建表必显式指定类型，宁可转换报错，不要静默当文本。
二、乱序导入废掉剪枝。不排序直接建表，行组的区间判据失效，过滤查询全量扫描。表现是"数据量没变、查询莫名变慢"。解法在建表时 ORDER BY（第7.2节决定二），事后补救是重建。
三、内存库当持久库。不传路径的连接是纯内存库，退出即消散。写了两小时的结果忘了落盘，这是新手最心疼的一课。规矩：正式工作永远显式打开文件库，内存库只做一次性验算。
四、长会话的内存驻留。查询结束，中间结果的内存并不立刻归还——引擎按自己的节奏回收（第2.2节）。表现为"跑了半天笔记本越来越挤"。解法是大任务分会话跑，或主动执行检查点让引擎落盘收紧。
五、把 star schema 的习惯带进来。服务端数仓里先 JOIN 再聚合是本能，嵌入式场景里，很多连接可以靠第7.2节的宽表冗余省掉——少一次哈希连接，少一份构建内存。
六、视图套视图套视图。视图存的是定义，嵌套五层的视图展开出五层子查询，优化器能压平一部分，可读性先崩掉。分析库里的视图保持一两层，复杂逻辑物化成表。
FAQ：三个常被问到的处境
报错说内存不够，但任务管理器里内存明明没满？
memory_limit 是引擎自己认的上限，默认低于物理内存是有意留白（给操作系统和其他进程）。报错时先看计划里哪个算子吃内存最凶，优先改查询（第7.1节第二层），实在需要再抬上限——无脑抬到物理内存总量，等于把溢出保护拆了。
同一条 SQL 昨天两秒今天二十秒，数据没变，为什么？
三个高概率方向按序排查：数据物理顺序变了吗（新导入的批次乱序追加，剪枝失效）；并发环境变了吗（别的工作负载在抢核或抢内存）；缓存状态变了吗（昨天热的行组今天冷了，第一遍慢是正常的，取中位数再判断）。
怎么判断该信计划还是该信实测？
都信，但各管各的：计划告诉你哪里贵（算子级耗时占比），实测告诉你多贵（总时长）。只看实测容易开错药方，只看计划容易 optimise 一个不存在的瓶颈。7.1 节的闭环就是让两者轮流说话。
把陷阱变成团队资产
清单的终局不是存在书里，是长在团队流程里。两个落点。建表模板：把第7.2节的四个决定做成团队统一的建表语句模板——类型逐列显式、ORDER BY 默认按时间，新人照模板写，一半的静默陷阱从源头消失。报错台账：团队里每遇到一个新报错，解掉之后在共享文档里添一行"报错原文、原因、解法"——本节的解码表就是这份台账的个人版起点，台账的生命力在于每次故障后的一行追加。半年后回看，台账会是你团队最值钱的技术文档，因为它记录的全是你们真实踩过的坑，而不是可能踩的。
报错翻译练习：三段真实现场
用三段改写自真实场景的报错做个自测，盖住右侧自己先归因：
| 报错现场 | 归因与动作 |
|---|---|
| 查询报某列不存在，但 SELECT 里明明写了它 | 别名作用域问题——WHERE 或 GROUP BY 里用了 SELECT 的别名，改用原始列名 |
| 加载远端 Parquet 报函数不存在，同事机器上却正常 | 扩展没加载——本会话缺 LOAD，对照第6.1节把 LOAD 写进脚本开头 |
| 导入新一批 CSV 报类型转换失败，上一批同样的流程没有报 | 上游格式变了——先 DESCRIBE 对比两批的嗅探结果，再决定 CAST 策略 |
三段的共同点值得点破：报错定位的往往不是病根。列名问题的病根在查询书写习惯，函数问题的病根在环境漂移，转换问题的病根在上游变更——解法都落在报错文本之外半步的地方。这也是报错台账比搜索引擎好用的根本原因：台账记的是"你环境里的因果链"，搜索结果只给"所有人的常见答案"。
本节要点回顾
- 报错前缀先分流：Binder 管名字、Conversion 管类型、OOM 管内存、IO 管文件锁。
- 文件锁是单写者硬约束：约定好谁在写，其余人只读打开。
- 静默陷阱贵过报错：类型降级、乱序废剪枝、内存库当持久库，三案最常见。
- 交付前过清单：六个静默陷阱逐条对，十分钟换一个睡得着的交付。
- 计划与实测各管一半：计划定位在哪，实测量化多贵，缺一不可。