// 错误参考
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
|
不支持的功能
无效的事务启动
| 代码 | 含义 |
|---|---|
0B000
|
invalid_transaction_initiation
|
定位器异常
| 代码 | 含义 |
|---|---|
0F000
|
locator_exception
|
0F001
|
invalid_locator_specification
|
无效的授权者
无效的角色指定
| 代码 | 含义 |
|---|---|
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
|
基数违规
数据异常
| 代码 | 含义 |
|---|---|
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 一并删除依赖对象。
|
无效的事务终止
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" 不存在
|
无效的目录名称
无效的模式名称
事务回滚
| 代码 | 含义 |
|---|---|
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
|
内部错误
// 一个客户端,覆盖所有引擎
更快地使用 PostgreSQL
SQLly 是 macOS、Windows 和 Linux 的原生 SQL 客户端,具备模式感知的 IntelliSense,并为高风险语句提供护栏。