22P03 — invalid_binary_representation

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.

English manual coverage begins with PostgreSQL 8.1. Source history and runtime observations have their own recorded version boundaries.

Reading PG 18·Select a recorded version

8.1 8.2 8.3 8.4 9.0 9.1 9.2 9.3 9.4 9.5 9.6 10 11 12 13 14 15 16 17 18 19 20

aliases: Unknown
class name: Data Exception
condition name: invalid_binary_representation
lang: en
sqlstate: 22P03

Definition PG 18

22P03

At a glance {#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 {#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 {#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 {#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 {#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 {#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.

Related {#related}

22P02, 22P04, 08P01

Sources {#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.

Compare versions

SQLSTATE evidence and recorded runtime versions

claims · identity

{
  "claim_id": "identity",
  "limits": "",
  "method": "Read fixed definition.",
  "position": 0,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "22P03 is invalid_binary_representation in SQLSTATE Class 22."
}

claims · protocol-and-copy

{
  "claim_id": "protocol-and-copy",
  "limits": "",
  "method": "Read the complete receive-and-cursor guards.",
  "position": 1,
  "runtime": [],
  "sources": [
    "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"
  ],
  "statement": "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."
}

claims · fastpath-and-replication

{
  "claim_id": "fastpath-and-replication",
  "limits": "",
  "method": "Read the complete binary branches and cursor reset/leftover checks.",
  "position": 2,
  "runtime": [],
  "sources": [
    "src.path.fastpath",
    "src.path.logicalrep"
  ],
  "statement": "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."
}

claims · type-receivers

{
  "claim_id": "type-receivers",
  "limits": "The listed type paths are representative, not an exhaustive inventory of all receive functions.",
  "method": "Read representative type receive guards.",
  "position": 3,
  "runtime": [],
  "sources": [
    "src.path.array",
    "src.path.array-elements",
    "src.path.numeric"
  ],
  "statement": "Built-in binary receive functions can emit 22P03 for invalid internal layouts, including array dimensions/flags/element framing and numeric sign/scale/digit fields."
}

claims · history

{
  "claim_id": "history",
  "limits": "",
  "method": "Use catalogue boundary.",
  "position": 4,
  "runtime": [],
  "sources": [
    "src.errcodes.18.6"
  ],
  "statement": "The locked catalogue records 22P03 from 7.4; that boundary does not prove exact implementation introduction."
}

messages · message.copy

{
  "limits": "",
  "message_id": "message.copy",
  "path": "",
  "position": 0,
  "raw": {
    "id": "message.copy",
    "primary_template": "incorrect binary data format",
    "severity_source": "ERROR",
    "sources": [
      "src.path.copy-binary"
    ],
    "sqlstate": "22P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.copy-binary"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "incorrect binary data format",
      "position": 0,
      "role": "",
      "template": "incorrect binary data format"
    }
  ]
}

messages · message.bind

{
  "limits": "",
  "message_id": "message.bind",
  "path": "",
  "position": 1,
  "raw": {
    "id": "message.bind",
    "primary_template": "incorrect binary data format in bind parameter %d",
    "severity_source": "ERROR",
    "sources": [
      "src.path.bind"
    ],
    "sqlstate": "22P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.bind"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "incorrect binary data format in bind parameter",
      "position": 0,
      "role": "",
      "template": "incorrect binary data format in bind parameter %d"
    }
  ]
}

messages · message.fastpath

{
  "limits": "",
  "message_id": "message.fastpath",
  "path": "",
  "position": 2,
  "raw": {
    "id": "message.fastpath",
    "primary_template": "incorrect binary data format in function argument %d",
    "severity_source": "ERROR",
    "sources": [
      "src.path.fastpath"
    ],
    "sqlstate": "22P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.fastpath"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "incorrect binary data format in function argument",
      "position": 0,
      "role": "",
      "template": "incorrect binary data format in function argument %d"
    }
  ]
}

messages · message.logicalrep

{
  "limits": "",
  "message_id": "message.logicalrep",
  "path": "",
  "position": 3,
  "raw": {
    "id": "message.logicalrep",
    "primary_template": "incorrect binary data format in logical replication column %d",
    "severity_source": "ERROR",
    "sources": [
      "src.path.logicalrep"
    ],
    "sqlstate": "22P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.logicalrep"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "incorrect binary data format in logical replication column",
      "position": 0,
      "role": "",
      "template": "incorrect binary data format in logical replication column %d"
    }
  ]
}

messages · message.array-dim

{
  "limits": "",
  "message_id": "message.array-dim",
  "path": "",
  "position": 4,
  "raw": {
    "id": "message.array-dim",
    "primary_template": "invalid number of dimensions: %d",
    "severity_source": "ERROR",
    "sources": [
      "src.path.array"
    ],
    "sqlstate": "22P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.array"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "invalid number of dimensions:",
      "position": 0,
      "role": "",
      "template": "invalid number of dimensions: %d"
    }
  ]
}

messages · message.array-flags

{
  "limits": "",
  "message_id": "message.array-flags",
  "path": "",
  "position": 5,
  "raw": {
    "id": "message.array-flags",
    "primary_template": "invalid array flags",
    "severity_source": "ERROR",
    "sources": [
      "src.path.array"
    ],
    "sqlstate": "22P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.array"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "invalid array flags",
      "position": 0,
      "role": "",
      "template": "invalid array flags"
    }
  ]
}

messages · message.array-data

{
  "limits": "",
  "message_id": "message.array-data",
  "path": "",
  "position": 6,
  "raw": {
    "id": "message.array-data",
    "primary_template": "insufficient data left in message",
    "severity_source": "ERROR",
    "sources": [
      "src.path.array-elements"
    ],
    "sqlstate": "22P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.array-elements"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "insufficient data left in message",
      "position": 0,
      "role": "",
      "template": "insufficient data left in message"
    }
  ]
}

messages · message.array-element

{
  "limits": "",
  "message_id": "message.array-element",
  "path": "",
  "position": 7,
  "raw": {
    "id": "message.array-element",
    "primary_template": "improper binary format in array element %d",
    "severity_source": "ERROR",
    "sources": [
      "src.path.array-elements"
    ],
    "sqlstate": "22P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.array-elements"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "improper binary format in array element",
      "position": 0,
      "role": "",
      "template": "improper binary format in array element %d"
    }
  ]
}

messages · message.numeric-sign

{
  "limits": "",
  "message_id": "message.numeric-sign",
  "path": "",
  "position": 8,
  "raw": {
    "id": "message.numeric-sign",
    "primary_template": "invalid sign in external \"numeric\" value",
    "severity_source": "ERROR",
    "sources": [
      "src.path.numeric"
    ],
    "sqlstate": "22P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.numeric"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "invalid sign in external \"numeric\" value",
      "position": 0,
      "role": "",
      "template": "invalid sign in external \"numeric\" value"
    }
  ]
}

messages · message.numeric-scale

{
  "limits": "",
  "message_id": "message.numeric-scale",
  "path": "",
  "position": 9,
  "raw": {
    "id": "message.numeric-scale",
    "primary_template": "invalid scale in external \"numeric\" value",
    "severity_source": "ERROR",
    "sources": [
      "src.path.numeric"
    ],
    "sqlstate": "22P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.numeric"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "invalid scale in external \"numeric\" value",
      "position": 0,
      "role": "",
      "template": "invalid scale in external \"numeric\" value"
    }
  ]
}

messages · message.numeric-digit

{
  "limits": "",
  "message_id": "message.numeric-digit",
  "path": "",
  "position": 10,
  "raw": {
    "id": "message.numeric-digit",
    "primary_template": "invalid digit in external \"numeric\" value",
    "severity_source": "ERROR",
    "sources": [
      "src.path.numeric"
    ],
    "sqlstate": "22P03"
  },
  "severity": "ERROR",
  "sources": [
    "src.path.numeric"
  ],
  "templates": [
    {
      "kind": "primary",
      "literal": "invalid digit in external \"numeric\" value",
      "position": 0,
      "role": "",
      "template": "invalid digit in external \"numeric\" value"
    }
  ]
}

sources · src.errcodes.18.6

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/errcodes.txt",
  "position": 0,
  "sha256": "6e8de346643ba84aa3c9c6a73360acfc7b2dfb89162c06c08ce9bf5bcd5bbcba",
  "source_id": "src.errcodes.18.6",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/errcodes.txt#L207"
}

sources · src.path.copy-binary

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/commands/copyfromparse.c",
  "position": 1,
  "sha256": "bc42754023579cd782a3cb3f144ad2c2c3d3aa46119eb7567fcdb05f2d445571",
  "source_id": "src.path.copy-binary",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/commands/copyfromparse.c#L2047"
}

sources · src.path.bind

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/tcop/postgres.c",
  "position": 2,
  "sha256": "9fb62275b1badf94d01ab351337b60410cd9b3ab1fe63fa9f23d6d2185a21061",
  "source_id": "src.path.bind",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/tcop/postgres.c#L1922"
}

sources · src.path.fastpath

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/tcop/fastpath.c",
  "position": 3,
  "sha256": "c42985c83293efe0bdf1c265930e0d4e13d6bb2eb23040815e638ad9244eab6c",
  "source_id": "src.path.fastpath",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/tcop/fastpath.c#L426"
}

sources · src.path.logicalrep

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/replication/logical/worker.c",
  "position": 4,
  "sha256": "096c5c46ffee6aab907ec5dad467100c5e3e8a4d398332d62dd302ab9c2ebf18",
  "source_id": "src.path.logicalrep",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/replication/logical/worker.c#L832"
}

sources · src.path.array

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/arrayfuncs.c",
  "position": 5,
  "sha256": "1f1c9dab1e5f8c936bbfe6c28a3011365b433367e1854166bbec9d2e97341177",
  "source_id": "src.path.array",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/arrayfuncs.c#L1296"
}

sources · src.path.array-elements

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/arrayfuncs.c",
  "position": 6,
  "sha256": "1f1c9dab1e5f8c936bbfe6c28a3011365b433367e1854166bbec9d2e97341177",
  "source_id": "src.path.array-elements",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/arrayfuncs.c#L1476"
}

sources · src.path.numeric

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/utils/adt/numeric.c",
  "position": 7,
  "sha256": "6cde7cd60b3330b83be35d1f014045f5fb5fe737f3c5db4c8ed4080b99f2b666",
  "source_id": "src.path.numeric",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/utils/adt/numeric.c#L1093"
}

sources · src.path.protocol-recovery

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/tcop/postgres.c",
  "position": 8,
  "sha256": "9fb62275b1badf94d01ab351337b60410cd9b3ab1fe63fa9f23d6d2185a21061",
  "source_id": "src.path.protocol-recovery",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/tcop/postgres.c#L4483"
}

sources · src.path.fastpath-dispatch

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/tcop/postgres.c",
  "position": 9,
  "sha256": "9fb62275b1badf94d01ab351337b60410cd9b3ab1fe63fa9f23d6d2185a21061",
  "source_id": "src.path.fastpath-dispatch",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/tcop/postgres.c#L4843"
}

sources · src.path.protocol-flags

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "",
  "kind": "upstream_source",
  "location": "",
  "path": "src/backend/tcop/postgres.c",
  "position": 10,
  "sha256": "9fb62275b1badf94d01ab351337b60410cd9b3ab1fe63fa9f23d6d2185a21061",
  "source_id": "src.path.protocol-flags",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/tcop/postgres.c#L416-L445"
}

sources · doc.protocol.copy

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "https://www.postgresql.org/docs/18/protocol.html",
  "kind": "upstream_source",
  "location": "",
  "path": "doc/src/sgml/protocol.sgml",
  "position": 11,
  "sha256": "745339e07ebbc2bb67d98b258e25772ada644ef26011e3cd6b3fcbb435235f89",
  "source_id": "doc.protocol.copy",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/doc/src/sgml/protocol.sgml#L1287-L1318"
}

sources · doc.protocol.status

{
  "commit": "724edf9bde9d356724ad384a2e196edc3c9f80f7",
  "docs_url": "https://www.postgresql.org/docs/18/protocol.html",
  "kind": "upstream_source",
  "location": "",
  "path": "doc/src/sgml/protocol.sgml",
  "position": 12,
  "sha256": "745339e07ebbc2bb67d98b258e25772ada644ef26011e3cd6b3fcbb435235f89",
  "source_id": "doc.protocol.status",
  "tag": "REL_18_6",
  "url": "https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/doc/src/sgml/protocol.sgml#L7821-L7823"
}

Source references

Original manual reference

Full definition and evidence JSON

Definition sources

center · PostgreSQL 18 · english-manuals:d52f31901b33c0a6734347a6d8cffa1130429a61723ad6c3ea1b538efbac3771

Text language: en · english-manuals:d52f31901b33c0a6734347a6d8cffa1130429a61723ad6c3ea1b538efbac3771