↑↓ 选择 ↵ 打开 ⌫ 改范围 完整检索页

pgsql.cc 提供对 postgresql.org 官网内容的中文翻译，由 Pigsty 团队维护。

百科 / 错误代码 / Class 22 数据异常

22P04 bad_copy_file_format

ERROR 源码确认 参考 未实测

类别
Class 22 数据异常
严重等级
ERROR
条件名
bad_copy_file_format
宏名称
ERRCODE_BAD_COPY_FILE_FORMAT
启用版本
7.4
状态
活跃

版本覆盖

  1. 18
  2. 17
  3. 16
  4. 15
  5. 14
  1. 13
  2. 12
  3. 11
  4. 10
  1. 19 beta
  2. 20 dev

速览

22P04 是 COPY 文件格式边界。固定解析器在二进制签名和头部、文本或 CSV 帧、头部/行字段数以及二进制字段长度错误时使用它。它表示 COPY 结构错误，不是所有值转换失败的统称。

含义

二进制输入会校验 PGCOPY 签名、flags、扩展长度、行字段数、字段长度和结束标记。代表性主消息包括 COPY file signature not recognized、invalid COPY file header (missing flags)、invalid COPY file header (wrong length)、row field count is %d, expected %d、invalid field size 和 unexpected EOF in COPY data。

文本和 CSV 有独立的帧检查。头部匹配可能报告 wrong number of fields in header line: got %d, expected %d 或列名不匹配；普通行可能报告 extra data after last expected column 或 missing data for column "%s"。CSV 引号和换行可能报告 unterminated CSV quoted field、unquoted carriage return found in data 或 unquoted newline found in data；文本模式使用对应的 literal ... found in data 消息和提示。帧已正确解析但值无法转换时通常属于 22P02；二进制类型接收函数留下未消费字节时可能是 22P03。

报文

固定源码中的代表性主消息均为 ERROR：

  • 二进制头部/字段：COPY file signature not recognized；invalid COPY file header (missing flags)；unrecognized critical flags in COPY file header；invalid COPY file header (missing length)；invalid COPY file header (wrong length)；invalid field size；unexpected EOF in COPY data。
  • 头部和行：wrong number of fields in header line: got %d, expected %d；column name mismatch in header line field %d: got "%s", expected "%s"；extra data after last expected column；missing data for column "%s"；row field count is %d, expected %d。
  • CSV 和行帧：unterminated CSV quoted field；literal carriage return found in data；unquoted carriage return found in data；literal newline found in data；unquoted newline found in data；end-of-copy marker is not alone on its line。回车/换行变体还会携带使用 \r、\n 或带引号 CSV 字段的源码提示。

报文模板

源码里的格式串，不是某一次运行的输出。%s 之类是占位符，实际报文会填入对象名与取值。适用范围一栏是核验时留下的原始英文记录，未经翻译。

主消息 COPY file signature not recognized

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 invalid COPY file header (missing flags)

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 unrecognized critical flags in COPY file header

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 invalid COPY file header (missing length)

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 invalid COPY file header (wrong length)

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 wrong number of fields in header line: got %d, expected %d

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 column name mismatch in header line field %d: got "%s", expected "%s"

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 extra data after last expected column

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 missing data for column "%s"

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 row field count is %d, expected %d

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 invalid field size

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 unexpected EOF in COPY data

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 unterminated CSV quoted field

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 literal carriage return found in data
HINT Use "\r" to represent carriage return.

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 unquoted carriage return found in data
HINT Use quoted CSV field to represent carriage return.

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 literal newline found in data
HINT Use "\n" to represent newline.

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 unquoted newline found in data
HINT Use quoted CSV field to represent newline.

来源：src/backend/commands/copyfromparse.c @ REL_18_6

主消息 end-of-copy marker is not alone on its line

来源：src/backend/commands/copyfromparse.c @ REL_18_6

诊断

先确定来源是文本、CSV、二进制 COPY 还是前端 COPY-in。保留完整主消息，因为它能定位解析阶段。依次检查二进制签名/标志位/长度、头部和目标列顺序、行字段数、CSV 引号/转义与换行规则，以及文本 COPY 的数据结束标记是否单独占行，之后再检查目标类型的输入转换。

ON_ERROR IGNORE 不是通用的坏行跳过开关。固定文本/CSV 路径会围绕安全的类型输入转换处理软错误，并可发出通知后跳过数据类型不兼容的行；头部、字段数、行帧、CSV 引号和二进制结构错误仍以 ERROR 抛出，不能都靠这个选项跳过。

处理

按声明的文本/CSV/二进制格式、目标列顺序，重新生成带正确头部、长度、引号和行格式的流。前端 COPY-in 出错时，按当前 COPY 子协议状态结束输入，适当时使用 CopyFail。如果 COPY 由扩展协议发起且后端发送 ErrorResponse，客户端应发送 Sync 并等待 ReadyForQuery；如果由 simple Query 发起，剩余查询消息会被丢弃，随后直接发送 ReadyForQuery；客户端不需要发送 Sync，消费该 ReadyForQuery 后再发送下一条查询。不要在 COPY-in 期间发送普通 SQL。显式事务中的 ERROR 要在协议边界恢复后执行 ROLLBACK 或 ROLLBACK TO SAVEPOINT；ReadyForQuery 只报告状态，不能替代事务恢复。ON_ERROR IGNORE 只可能适用于文档所说的安全类型输入失败，不能修复坏头或损坏的 CSV/二进制帧。普通 COPY ERROR 本身不要求重置连接。

版本

锁定目录从 PostgreSQL 7.4 记录此条件。引用的解析器及 ON_ERROR 边界来自 PostgreSQL 18.6 REL_18_6；本次没有运行自然 COPY 文件案例。

来源

证据

断言

每条断言都写明了是怎么核实的，以及它不覆盖什么。这一层是核验时留下的原始英文记录，照原样呈现，未经翻译。

同类错误代码

Class 22 数据异常 下的其他成员。