↑↓ select ↵ open ⌫ change scope Open full search

PG.CENTER connects PostgreSQL documentation, reference, and ecosystem knowledge. Maintained by Pigsty.

SQLSTATE / CLASS 22 · DATA EXCEPTION

22P03

Read PG 18 manual ↗

invalid_binary_representation

SQLSTATE
22P03
Condition name
invalid_binary_representation
Class
Data Exception
Source macro
ERRCODE_INVALID_BINARY_REPRESENTATION
Evidence
Source path confirmed
Analysis & operational context

English SQLSTATE atlas: authored explanations and source/runtime evidence are separate from the manual definitions. View source ↗

<h1>22P03</h1>

At a glance

22P03 is PostgreSQL's invalid-binary-representation boundary. In the fixed source it covers binary COPY fields, extended-protocol Bind parameters, fast-path function arguments, logical-replication columns, and guards inside representative type receive functions.

Meaning

The receiver has been told to decode binary bytes, but the bytes do not satisfy the receiver's format or do not get consumed completely. Binary COPY calls a type receive function and reports incorrect binary data format when bytes remain. Bind reports incorrect binary data format in bind parameter %d; fast-path calls report incorrect binary data format in function argument %d; logical replication reports incorrect binary data format in logical replication column %d. Representative array and numeric receivers use the same SQLSTATE for invalid dimensions/flags, array element framing, or numeric sign/scale/digit fields.

This is different from text input that fails a type input routine, and from COPY header or row framing errors that use 22P04. The exact receiving boundary and type OID matter.

Messages

The fixed representative primaries are incorrect binary data format (binary COPY), incorrect binary data format in bind parameter %d (Bind), incorrect binary data format in function argument %d (fast-path), and incorrect binary data format in logical replication column %d (logical replication). Type receivers also use invalid number of dimensions: %d, invalid array flags, insufficient data left in message, improper binary format in array element %d, invalid sign in external "numeric" value, invalid scale in external "numeric" value, and invalid digit in external "numeric" value; all cited variants are ERROR and have no DETAIL or HINT in the fixed calls.

Diagnosis

First identify the transport: extended-protocol Bind, binary COPY, fast-path function call, logical replication, or a type's binary receive function. Preserve the parameter, argument, or remote-column number and the complete message. Compare the producer's format code and type OID with the receiver's expected type. For receiver guards, check whether the type consumed the complete length-delimited buffer; a leftover cursor is evidence of a format mismatch, not merely a bad textual value.

Response

Correct the producer or type contract, then retry at the protocol boundary that failed. Every client-visible ERROR inside an explicit transaction leaves that transaction aborted, including a Bind error: issue ROLLBACK or an already-established ROLLBACK TO SAVEPOINT before retrying. Sync and ReadyForQuery restore protocol synchronization and report status; they do not clear INERROR. For an extended-protocol Bind error, the backend skips frontend messages until the next Sync; send Sync and consume ReadyForQuery before issuing another extended-protocol operation. In autocommit, wait for that boundary before resubmitting the corrected operation. A fast-path FunctionCall is handled outside the extended-query skip flag and the normal loop can return ReadyForQuery, but the same explicit-transaction recovery rule applies. For COPY FROM STDIN, terminate a malformed stream according to the COPY protocol, using CopyFail when appropriate while still in COPY-in. If the COPY was issued through the extended protocol, after ErrorResponse send Sync and wait for ReadyForQuery; if it was issued in a simple Query, the remaining query message is discarded and ReadyForQuery follows; no client Sync is required, so consume that ReadyForQuery before sending the next query. Do not issue ordinary SQL during COPY-in. If message framing itself was lost while reading from the client, PostgreSQL has a separate protocol-synchronization FATAL path; do not infer that connection loss from the binary-format ERROR alone. For logical replication, repair the publisher/receiver binary encoder or type definition and let the replication worker's own retry policy apply; this page does not justify killing or resetting every connection.

Versions

The locked catalogue records this condition from PostgreSQL 7.4. The binary transport, replication, array, and numeric paths cited here are from PostgreSQL 18.6 REL_18_6; no binary-protocol runtime was executed.

Sources

src/backend/commands/copyfromparse.c#L2047-L2055

src/backend/tcop/postgres.c#L1922-L1945

src/backend/tcop/fastpath.c#L426-L448

src/backend/replication/logical/worker.c#L832-L853

src/backend/utils/adt/arrayfuncs.c#L1476-L1510

src/backend/utils/adt/numeric.c#L1093-L1123

src/backend/tcop/postgres.c#L416-L445

src/backend/tcop/postgres.c#L4483-L4504

src/backend/tcop/postgres.c#L4843-L4875

doc/src/sgml/protocol.sgml#L1287-L1318

doc/src/sgml/protocol.sgml#L7821-L7823

The structured evidence record records exact primary templates and the source/runtime boundary.

Source evidence

Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.

22P03 is invalid_binary_representation in SQLSTATE Class 22.

Method: Read fixed definition.

src.errcodes.18.6

Binary COPY and extended-protocol Bind call a type receive function and reject leftover bytes after the receiver returns; COPY uses the unqualified primary and Bind names the parameter number. The frontend loop marks Bind/Parse for skip-until-Sync recovery, while FunctionCall and COPY data are not marked by that extended-query flag. The protocol documentation distinguishes extended-query COPY (ErrorResponse, then Sync and ReadyForQuery) from simple Query COPY (discard the rest of the query and send ReadyForQuery without Sync); ReadyForQuery reports status but does not itself clear an aborted transaction. A separate protocol-synchronization loss path is FATAL.

Method: Read the complete receive-and-cursor guards.

src.path.copy-binary src.path.bind src.path.protocol-flags src.path.protocol-recovery src.path.fastpath-dispatch doc.protocol.copy doc.protocol.status

Fast-path arguments and logical-replication binary columns use the same consume-the-whole-buffer guard, with argument or remote-column context in the primary. Logical replication resets the StringInfo cursor before receive because some paths reparse the tuple.

Method: Read the complete binary branches and cursor reset/leftover checks.

src.path.fastpath src.path.logicalrep

Built-in binary receive functions can emit 22P03 for invalid internal layouts, including array dimensions/flags/element framing and numeric sign/scale/digit fields.

Method: Read representative type receive guards.

Limits: The listed type paths are representative, not an exhaustive inventory of all receive functions.

src.path.array src.path.array-elements src.path.numeric

The locked catalogue records 22P03 from 7.4; that boundary does not prove exact implementation introduction.

Method: Use catalogue boundary.

src.errcodes.18.6

Message templates

ERROR · message.copy

Primary

incorrect binary data format
ERROR · message.bind

Primary

incorrect binary data format in bind parameter %d
ERROR · message.fastpath

Primary

incorrect binary data format in function argument %d
ERROR · message.logicalrep

Primary

incorrect binary data format in logical replication column %d
ERROR · message.array-dim

Primary

invalid number of dimensions: %d
ERROR · message.array-flags

Primary

invalid array flags
ERROR · message.array-data

Primary

insufficient data left in message
ERROR · message.array-element

Primary

improper binary format in array element %d
ERROR · message.numeric-sign

Primary

invalid sign in external "numeric" value
ERROR · message.numeric-scale

Primary

invalid scale in external "numeric" value
ERROR · message.numeric-digit

Primary

invalid digit in external "numeric" value

Reproduction & repair cases

No reproduction case is attached to this condition.

Recorded runtime evidence

No runtime observation is attached to this entry.

Definition snapshot: english-manuals:b9ff15f5e89cf16b1c971bed512… · English manual source