// 錯誤參考

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 授權選項只能授予角色

無效的角色規格

程式碼意義
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 null 值違反 not-null 限制 not_null_violation 關聯 "users" 的欄位 "email" 中的 null 值違反 not-null 限制 詳細資訊:失敗的資料列包含 (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_violation 關聯 "orders" 的新資料列違反 CHECK 限制 "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 的 ShareLock;被處理程序 4321 封鎖。處理程序 4321 正在等待交易 8765 的 ShareLock;被處理程序 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" 的類型是帶時區的時間戳記,但運算式的類型是整數 提示:你需要重寫或轉換該運算式。
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 索引 "documents_body_idx" 的索引列大小 3200 超過 btree 版本 4 的上限 2704,詳細資訊:索引列參照關聯 "documents" 中的元組 (12,3)。提示:超過緩衝區頁面 1/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,並為有風險的語句提供防護欄。