// 错误参考

PostgreSQL 错误代码

PostgreSQL 能抛出的每个 SQLSTATE 代码,按官方附录的类别分组。实际常遇到的那些有完整页面:错误是什么意思、为什么会发生、怎么修。

解读 PostgreSQL 错误

PostgreSQL 通过五个字符的 SQLSTATE 代码识别每个错误。前两个字符表示类别: 23 表示完整性约束冲突, 42 表示语法错误或访问规则冲突, 40 表示事务回滚,等等。以 000 是所属类别的通用代码。

psql 显示消息,而不是代码。运行 \set VERBOSITY verbose 以查看 SQLSTATE,或从您的驱动程序读取: SQLSTATE 在 JDBC 和 ODBC 中, e.pgcode 在 psycopg2 中, e.sqlstate 在 psycopg 3 中, err.code 在 node-postgres 中。

在 PL/pgSQL 中,你可以通过条件名 (EXCEPTION WHEN unique_violation THEN)或按代码(WHEN SQLSTATE '23505' THEN).

本参考中的所有 PostgreSQL 错误

262 个代码,其中 63 个有完整说明(附链接)。代码和消息来自 PostgreSQL 文档,附录 A:PostgreSQL 错误代码.

成功完成

代码含义
00000 successful_completion

警告

代码含义
01000 warning
0100C dynamic_result_sets_returned
01008 implicit_zero_bit_padding
01003 null_value_eliminated_in_set_function
01007 privilege_not_granted
01006 privilege_not_revoked
01004 string_data_right_truncation
01P01 deprecated_feature

无数据(根据 SQL 标准,这也是一种警告类)

代码含义
02000 no_data
02001 no_additional_dynamic_result_sets_returned

SQL 语句尚未完成

代码含义
03000 sql_statement_not_yet_complete

连接异常

代码含义
08000 connection_exception
08003 connection_does_not_exist
08006 连接失败 connection_failure 服务器意外关闭连接。这可能意味着服务器在处理请求之前或过程中异常终止。
08001 无法建立连接 sqlclient_unable_to_establish_sqlconnection 连接到服务器 "db.example.com" (10.0.0.5),端口 5432 失败:连接被拒绝。服务器是否在该主机上运行并接受 TCP/IP 连接?
08004 sqlserver_rejected_establishment_of_sqlconnection
08007 transaction_resolution_unknown
08P01 protocol_violation

触发操作异常

代码含义
09000 triggered_action_exception

不支持的功能

代码含义
0A000 功能不受支持 feature_not_supported 未实现跨数据库引用:"otherdb.public.orders"

无效的事务启动

代码含义
0B000 invalid_transaction_initiation

定位器异常

代码含义
0F000 locator_exception
0F001 invalid_locator_specification

无效的授权者

代码含义
0L000 invalid_grantor
0LP01 无效的授权操作 invalid_grant_operation GRANT OPTION 只能授予角色

无效的角色指定

代码含义
0P000 invalid_role_specification

诊断异常

代码含义
0Z000 diagnostics_exception
0Z002 stacked_diagnostics_accessed_without_active_handler

XQuery 错误

代码含义
10608 invalid_argument_for_xquery

未找到 CASE 分支

代码含义
20000 case_not_found

基数违规

代码含义
21000 子查询返回多于一行 cardinality_violation 用作表达式的子查询返回了多行

数据异常

代码含义
22000 data_exception
2202E array_subscript_error
22021 编码的字节序列无效 character_not_in_repertoire 编码 "UTF8" 的无效字节序列:0xff
22008 日期/时间字段值超出范围 datetime_field_overflow 日期/时间字段值超出范围:"2026-13-01"
22012 除以零 division_by_zero 除以零
22005 error_in_assignment
2200B escape_character_conflict
22022 indicator_overflow
22015 interval_field_overflow
2201E invalid_argument_for_logarithm
22014 invalid_argument_for_ntile_function
22016 invalid_argument_for_nth_value_function
2201F invalid_argument_for_power_function
2201G invalid_argument_for_width_bucket_function
22018 invalid_character_value_for_cast
22007 无效的日期时间格式 invalid_datetime_format 时间戳类型的输入语法无效:"31/12/2026 25:00"
22019 invalid_escape_character
2200D invalid_escape_octet
22025 invalid_escape_sequence
22P06 nonstandard_use_of_escape_character
22010 invalid_indicator_parameter_value
22023 无效的参数值 invalid_parameter_value 参数 "TimeZone" 的值无效:"Mars/Olympus"
22013 invalid_preceding_or_following_size
2201B invalid_regular_expression
2201W invalid_row_count_in_limit_clause
2201X invalid_row_count_in_result_offset_clause
2202H invalid_tablesample_argument
2202G invalid_tablesample_repeat
22009 invalid_time_zone_displacement_value
2200C invalid_use_of_escape_character
2200G most_specific_type_mismatch
22004 null_value_not_allowed
22002 null_value_no_indicator_parameter
22003 数值超出范围 numeric_value_out_of_range 整数超出范围
2200H sequence_generator_limit_exceeded
22026 string_data_length_mismatch
22001 值对于该类型来说过长 string_data_right_truncation 值对于 character varying(20) 类型来说过长
22011 substring_error
22027 trim_error
22024 unterminated_c_string
2200F zero_length_character_string
22P01 floating_point_exception
22P02 类型的输入语法无效 invalid_text_representation 整数类型的输入语法无效:"abc"
22P03 invalid_binary_representation
22P04 bad_copy_file_format
22P05 untranslatable_character
2200L not_an_xml_document
2200M invalid_xml_document
2200N invalid_xml_content
2200S invalid_xml_comment
2200T invalid_xml_processing_instruction
22030 duplicate_json_object_key_value
22031 invalid_argument_for_sql_json_datetime_function
22032 invalid_json_text
22033 invalid_sql_json_subscript
22034 more_than_one_sql_json_item
22035 no_sql_json_item
22036 non_numeric_sql_json_item
22037 non_unique_keys_in_a_json_object
22038 singleton_sql_json_item_required
22039 sql_json_array_not_found
2203A sql_json_member_not_found
2203B sql_json_number_not_found
2203C sql_json_object_not_found
2203D too_many_json_array_elements
2203E too_many_json_object_members
2203F sql_json_scalar_required
2203G sql_json_item_cannot_be_cast_to_target_type

违反完整性约束

代码含义
23000 integrity_constraint_violation
23001 restrict_violation
23502 空值违反非空约束 not_null_violation 关系“users”的列“email”中的空值违反非空约束 详情:失败的行包含 (7, Ada, null)。
23503 外键约束冲突 foreign_key_violation 对表“orders”的插入或更新违反外键约束“orders_customer_id_fkey” 详情:键 (customer_id)=(42) 在表“customers”中不存在。
23505 重复键违反唯一约束 unique_violation 重复键值违反唯一约束“users_email_key” 详情:键 (email)=([email protected]) 已存在。
23514 CHECK 约束冲突 check_violation 关系 "orders" 的新行违反了检查约束 "orders_qty_check" 详细信息:失败的行包含 (12, -1)。
23P01 违反排他约束 exclusion_violation 冲突的键值违反排他约束 "bookings_room_during_excl" 详细信息:键 (room_id, during)=(4, ["2026-05-01 10:00:00","2026-05-01 11:00:00")) 与现有键 (room_id, during)=(4, ["2026-05-01 10:30:00","2026-05-01 12:00:00")) 冲突。

无效的游标状态

代码含义
24000 invalid_cursor_state

无效的事务状态

代码含义
25000 invalid_transaction_state
25001 无法在事务块内运行 active_sql_transaction CREATE INDEX CONCURRENTLY 无法在事务块内运行
25002 branch_transaction_already_active
25008 held_cursor_requires_same_isolation_level
25003 inappropriate_access_mode_for_branch_transaction
25004 inappropriate_isolation_level_for_branch_transaction
25005 no_active_sql_transaction_for_branch_transaction
25006 只读 SQL 事务 read_only_sql_transaction 无法在只读事务中执行 INSERT
25007 schema_and_data_statement_mixing_not_supported
25P01 no_active_sql_transaction
25P02 当前事务已中止 in_failed_sql_transaction 当前事务已中止,事务块结束前命令将被忽略
25P03 事务内空闲会话超时 idle_in_transaction_session_timeout 由于事务空闲超时而终止连接
25P04 transaction_timeout

无效的 SQL 语句名称

代码含义
26000 invalid_sql_statement_name

触发的数据更改违规

代码含义
27000 triggered_data_change_violation

无效的授权规范

代码含义
28000 无效的授权规范 invalid_authorization_specification 没有主机 “10.0.0.5”、用户 “app”、数据库 “shop” 的 pg_hba.conf 条目,且未启用加密
28P01 密码认证失败 invalid_password 用户 "app" 的密码认证失败

仍然存在依赖的权限描述符

代码含义
2B000 dependent_privilege_descriptors_still_exist
2BP01 依赖对象仍然存在 dependent_objects_still_exist 无法删除表 customers,因为其他对象依赖它 详细信息:表 orders 上的约束 orders_customer_id_fkey 依赖于表 customers 提示:使用 DROP ... CASCADE 一并删除依赖对象。

无效的事务终止

代码含义
2D000 无效的事务终止 invalid_transaction_termination 无效的事务终止

SQL 例程异常

代码含义
2F000 sql_routine_exception
2F005 function_executed_no_return_statement
2F002 modifying_sql_data_not_permitted
2F003 prohibited_sql_statement_attempted
2F004 reading_sql_data_not_permitted

无效的游标名称

代码含义
34000 invalid_cursor_name

外部例程异常

代码含义
38000 external_routine_exception
38001 containing_sql_not_permitted
38002 modifying_sql_data_not_permitted
38003 prohibited_sql_statement_attempted
38004 reading_sql_data_not_permitted

外部例程调用异常

代码含义
39000 external_routine_invocation_exception
39001 invalid_sqlstate_returned
39004 null_value_not_allowed
39P01 trigger_protocol_violated
39P02 srf_protocol_violated
39P03 event_trigger_protocol_violated

保存点异常

代码含义
3B000 savepoint_exception
3B001 无效的保存点规范 invalid_savepoint_specification 保存点 "before_update" 不存在

无效的目录名称

代码含义
3D000 数据库不存在 invalid_catalog_name 数据库 "shop" 不存在

无效的模式名称

代码含义
3F000 模式不存在 invalid_schema_name 模式 "sales" 不存在

事务回滚

代码含义
40000 transaction_rollback
40002 transaction_integrity_constraint_violation
40001 无法序列化访问 serialization_failure 由于并发更新,无法序列化访问
40003 statement_completion_unknown
40P01 检测到死锁 deadlock_detected 检测到死锁 详情:进程 1234 等待事务 5678 的共享锁;被进程 4321 阻塞。进程 4321 等待事务 8765 的共享锁;被进程 1234 阻塞。

语法错误或访问规则违规

代码含义
42000 syntax_error_or_access_rule_violation
42601 语法错误,出现在或其附近 syntax_error 在 "FROM" 处或附近出现语法错误 行 1: SELECT id, name, FROM users; ^
42501 权限被拒绝 insufficient_privilege 对表 orders 的权限被拒绝
42846 无法强制转换 cannot_coerce 无法将类型 integer 转换为 uuid
42803 列必须出现在 GROUP BY 子句中 grouping_error 列 "o.customer_id" 必须出现在 GROUP BY 子句中或用于聚合函数
42P20 windowing_error
42P19 invalid_recursion
42830 外键无效 invalid_foreign_key 被引用表 “customers” 中没有与给定键匹配的唯一约束
42602 invalid_name
42622 name_too_long
42939 reserved_name
42804 数据类型不匹配 datatype_mismatch 列 "created_at" 的类型是 timestamp with time zone,但表达式的类型是 integer 提示:你需要重写表达式或转换它的类型。
42P18 无法确定参数的数据类型 indeterminate_datatype 无法确定参数 $1 的数据类型
42P21 collation_mismatch
42P22 indeterminate_collation
42809 wrong_object_type
428C9 generated_always
42703 列不存在 undefined_column 列 "emial" 不存在 第 1 行: SELECT emial FROM users; ^ 提示:也许你想引用的其实是列 "users.email"。
42883 函数不存在 undefined_function 函数 lower(integer) 不存在 第 1 行:SELECT lower(42); ^ 提示:没有与给定名称和参数类型匹配的函数。你可能需要添加显式的类型转换。
42P01 关系不存在 undefined_table 关系 "orders" 不存在 第 1 行:SELECT * FROM orders; ^
42P02 没有参数 undefined_parameter 没有参数 $1
42704 未定义对象 undefined_object 类型 “jsonbb” 不存在
42701 duplicate_column
42P03 duplicate_cursor
42P04 数据库已存在 duplicate_database 数据库 "shop" 已存在
42723 duplicate_function
42P05 duplicate_prepared_statement
42P06 模式已存在 duplicate_schema 模式 "sales" 已存在
42P07 关系已存在 duplicate_table 关系“orders”已存在
42712 duplicate_alias
42710 对象重复 duplicate_object 角色“app”已存在
42702 列引用不明确 ambiguous_column 列引用 "id" 不明确 第 1 行: SELECT id FROM orders JOIN customers ON customers.id = orders.customer_id; ^
42725 ambiguous_function
42P08 ambiguous_parameter
42P09 ambiguous_alias
42P10 无效的列引用 invalid_column_reference 没有与 ON CONFLICT 规范匹配的唯一约束或排他约束
42611 invalid_column_definition
42P11 invalid_cursor_definition
42P12 invalid_database_definition
42P13 invalid_function_definition
42P14 invalid_prepared_statement_definition
42P15 invalid_schema_definition
42P16 invalid_table_definition
42P17 invalid_object_definition

违反 WITH CHECK OPTION

代码含义
44000 with_check_option_violation

资源不足

代码含义
53000 insufficient_resources
53100 磁盘已满 disk_full 无法扩展文件“base/16384/16397”:设备上没有剩余空间 提示:检查可用磁盘空间。
53200 内存不足 out_of_memory 内存不足 详细信息:在内存上下文 “ExecutorState” 中请求大小 1048576 失败。
53300 连接过多 too_many_connections 抱歉,客户端已经太多了
53400 configuration_limit_exceeded

超出程序限制

代码含义
54000 程序限制超出 program_limit_exceeded 索引行大小 3200 超过索引 "documents_body_idx" 的 btree 版本 4 最大值 2704 详细信息:索引行引用了关系 "documents" 中的元组 (12,3)。提示:超过缓冲区页面三分之一的值不能被索引。考虑使用该值的 MD5 哈希函数索引,或使用全文索引。
54001 statement_too_complex
54011 too_many_columns
54023 too_many_arguments

对象不处于先决条件状态

代码含义
55000 对象不处于先决条件状态 object_not_in_prerequisite_state 序列 "orders_id_seq" 的 currval 在本会话中尚未定义
55006 对象正在使用中 object_in_use 数据库“shop”正在被其他用户访问 详情:有 1 个其他会话正在使用该数据库。
55P02 cant_change_runtime_param
55P03 锁不可用 lock_not_available 无法在关系“orders”的行上获得锁
55P04 unsafe_new_enum_value_usage

操作员干预

代码含义
57000 operator_intervention
57014 正在取消语句 query_canceled 由于语句超时,正在取消语句
57P01 因管理员操作终止连接 admin_shutdown 因管理员命令终止连接
57P02 crash_shutdown
57P03 现在无法连接 cannot_connect_now 数据库系统正在启动
57P04 database_dropped
57P05 idle_session_timeout

系统错误(PostgreSQL 本身以外的错误)

代码含义
58000 system_error
58030 io_error
58P01 未定义文件 undefined_file 无法打开文件“/tmp/orders.csv”进行读取:没有此类文件或目录
58P02 duplicate_file
58P03 file_name_too_long

配置文件错误

代码含义
F0000 config_file_error
F0001 lock_file_exists

外部数据包装器错误(SQL/MED)

代码含义
HV000 fdw_error
HV005 fdw_column_name_not_found
HV002 fdw_dynamic_parameter_value_needed
HV010 fdw_function_sequence_error
HV021 fdw_inconsistent_descriptor_information
HV024 fdw_invalid_attribute_value
HV007 fdw_invalid_column_name
HV008 fdw_invalid_column_number
HV004 fdw_invalid_data_type
HV006 fdw_invalid_data_type_descriptors
HV091 fdw_invalid_descriptor_field_identifier
HV00B fdw_invalid_handle
HV00C fdw_invalid_option_index
HV00D fdw_invalid_option_name
HV090 fdw_invalid_string_length_or_buffer_length
HV00A fdw_invalid_string_format
HV009 fdw_invalid_use_of_null_pointer
HV014 fdw_too_many_handles
HV001 fdw_out_of_memory
HV00P fdw_no_schemas
HV00J fdw_option_name_not_found
HV00K fdw_reply_handle
HV00Q fdw_schema_not_found
HV00R fdw_table_not_found
HV00L fdw_unable_to_create_execution
HV00M fdw_unable_to_create_reply
HV00N fdw_unable_to_establish_connection

PL/pgSQL 错误

代码含义
P0000 plpgsql_error
P0001 引发异常 raise_exception 账户 42 资金不足
P0002 no_data_found
P0003 too_many_rows
P0004 assert_failure

内部错误

代码含义
XX000 内部错误 internal_error 关系 16397 的缓存查找失败
XX001 数据损坏 data_corrupted 关系 base/16384/16397 的块 1234 中的页面无效
XX002 index_corrupted
// 一个客户端,覆盖所有引擎

更快地使用 PostgreSQL

SQLly 是 macOS、Windows 和 Linux 的原生 SQL 客户端,具备模式感知的 IntelliSense,并为高风险语句提供护栏。