22001

速览

固定 varchar 路径报告 value too long for type character(%d)；hstore、varbit 等路径会使用各自的具体变体。

共享案例创建 varchar_limits(value varchar(3))，用 'too-long' 触发 22001，再插入修复值 'ok' 并查询存储值。应在自动提交下逐条发送这些语句：触发语句预期失败，之后再执行修复语句。案例运行器在结束阶段负责清理对象。

CREATE TABLE varchar_limits (value varchar(3));
INSERT INTO varchar_limits VALUES ('too-long');
INSERT INTO varchar_limits VALUES ('ok');
SELECT value FROM varchar_limits;

校准实测 character varying(3) 拒绝超长值并报告 value too long for type character varying(3)；修正值 ok 成功，运行器的两条自动提交会话均回到 IDLE。

报文

固定 character 和 varchar guard 以 ERROR 严重性报告 primary 模板 value too long for type character(%d) 与 value too long for type character varying(%d)。hstore 与 varbit 路径使用各自的 primary：string too long for hstore key、string too long for hstore value 和 bit string too long for type bit varying(%d)。这些源码组没有独立 DETAIL 或 HINT；本次运行只观察了上面的 varchar 模板。

含义

当值无法满足字符串类型的长度契约时会出现 22001。PostgreSQL 按字符数而不是字节数计算 character(n) 和 character varying(n)，因此 value too long for type character(%d) 中的 %d 指向响应里的 typmod。固定 varchar.c 是服务器端检查；hstore 键值和 bit string 有各自的路径和消息。

值进入类型的方式也会改变边界。varchar() 和 bpchar() 都接收 isExplicit 标志：赋值/输入转换遇到超出的非空格字符会报错，而显式 cast 到有界类型可以按 PostgreSQL 字符类型规则截断；超出的尾随空格和非空格字符处理不同。修改存储或校验前应先明确这个选择。

诊断

保存 schema_name、table_name、column_name、datatype_name、routine 和完整 message。先从目录确认目标类型和 typmod，再按字符数而不是字节数测量实际值。区分赋值/插入、显式 cast，以及 hstore/bit 路径，因为它们的截断行为并不完全相同。

常见 varchar 路径要检查超出宽度的后缀是否全是尾随空格。只有尾随空格超出时可能适用字符类型的截断规则；有意义的非空格数据应视为契约被拒绝。固定源码消息说明的是类型宽度问题，不是一般编码或网络错误。

处置

选择能保留数据契约的修复：校验并拒绝超长输入，有意扩大列/类型，或只在业务明确允许时显式 cast 截断。截断前保存原值和目标 typmod；静默裁剪标识符、键或审计文本可能写入与调用方意图不同的内容。本次固定案例使用自动提交，失败语句结束后会话仍为 IDLE；显式事务中应先回滚整个事务，或回滚到语句前建立的保存点，再重试修正值。修正输入或 schema 后重新转换，并核对保存后的字符长度。

版本

锁定目录从 7.4 记录该条件，并在列出的正式快照及 19beta3 中出现；固定源码覆盖为 PostgreSQL 18.6。

相关条件

22003 是数值/范围越界，22007 是日期时间格式错误，22004 是独立的 NULL 契约。

来源

固定 character(n) 检查见 varchar.c#L300-L313，character varying(n) 检查见 varchar.c#L633-L640。PostgreSQL 18 的字符类型文档说明了字符数限制、尾随空格和显式 cast。结构化证据记录固定了源码 SHA，并区分 hstore/varbit 变体。