↑↓ select ↵ open ⌫ change scope Open full search

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

SQLSTATE / CLASS 08 · CONNECTION EXCEPTION

08006

Read PG 18 manual ↗

connection_failure

SQLSTATE
08006
Condition name
connection_failure
Class
Connection Exception
Source macro
ERRCODE_CONNECTION_FAILURE
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>08006</h1>

At a glance

SQLSTATE 08006 is connection_failure in Class 08. 08006 names failure of an established connection. The fixed paths include postgres_fdw cancel/connection-loss handling and COPY failure handling; they do not define one universal primary or severity, and this batch intentionally has no generic socket run.

Meaning

The fixed source paths show why this class cannot have one universal message. In postgres_fdw, a failed cancel request reports a WARNING while the established foreign connection is being handled; this warning is a diagnostic from the cancel path, not by itself proof that the client session was terminated. In the COPY paths, an open-transaction client EOF is reported as an ERROR, while the older COPY-to-stdout path reports FATAL when the output connection is lost. The severity and phase are part of the meaning: these branches must not be collapsed into “the socket broke”.

An ERROR branch can leave a still-connected session in INERROR when it occurs inside an explicit transaction, so the caller must recover with ROLLBACK or an appropriate savepoint before issuing unrelated SQL. A FATAL branch ends the backend connection; there is no session on which to send ROLLBACK. A client socket that has already reached EOF can also leave the client with no SQLSTATE at all. The evidence here confirms these source branches, but does not claim that every ordinary network disconnect emits 08006.

Branch guide

Fixed branch What it tells you First diagnostic action
postgres_fdw cancel WARNING A cancel request could not be sent or its result could not be read on an established foreign connection. Preserve the dynamic libpq text, FDW operation, and local transaction state; the warning alone does not establish that the local session was closed.
COPY client EOF ERROR The server detected EOF while a COPY-related connection still had an open transaction. The triggering client socket has already reached EOF, so it cannot receive ROLLBACK or be reused; reconnect and reconcile the COPY outcome.
COPY-to-stdout FATAL The fixed 10.23 path lost the output connection while COPY was running and used fatal severity. Discard the backend connection and reconcile any data already sent or received; no session-level rollback is possible.
Ordinary client EOF The peer disappeared before or outside one of the fixed server branches. Use the driver/socket and server log evidence; do not assign 08006 from a null client SQLSTATE alone.

Diagnosis

Correlate backend PID, operation, server log fields, and the client exception. A client-side broken socket can expose SQLSTATE null, while a server-side FDW or COPY path may emit 08006 with path-specific text. Distinguish it from 08001 (no connection was established), 08007/40003 (completion uncertainty), and a normal statement error before deciding whether work may have completed.

Check severity and lifecycle together. WARNING means the FDW cancel branch may still have a live local session; ERROR means inspect INERROR versus IDLE and recover the transaction if needed; FATAL means the backend is gone. If the client saw EOF before an ErrorResponse, the absence of a SQLSTATE is expected evidence of a lost protocol exchange, not proof of 08006.

Response

Discard a connection the pool marks broken, reconcile remote or non-idempotent work, and retry only a complete operation under an explicit idempotency policy. The fixed source paths are useful boundaries here; no artificial RAISE, timeout, or ordinary socket close is counted as observed 08006.

For an independently still-connected ERROR case, roll back the failed explicit transaction (or roll back to a savepoint intentionally established around the operation), then decide whether the complete operation can be retried. That generic transaction rule does not prove that the COPY client-EOF socket is reusable: the source branch has already detected EOF on that client connection. For FATAL or an already-lost socket, establish a fresh session and reconcile the outcome before replaying anything. Autocommit does not make a remote or COPY operation idempotent; it only changes the local transaction boundary.

Messages

The fixed branches include these distinct diagnostics:

  • WARNING could not send cancel request: %s from the postgres_fdw cancel path; the libpq error text is dynamic.
  • WARNING could not get result of cancel request: %s from the same FDW path; the returned connection error text is dynamic.
  • FATAL connection lost during COPY to stdout in the fixed 10.23 COPY path.
  • ERROR unexpected EOF on client connection with an open transaction in the fixed 18.6/10.23 COPY client-EOF paths.

The evidence keeps these as separate variants and does not turn an ordinary client-side null SQLSTATE into 08006.

The ERROR and FATAL variants have different recovery contracts even when their text mentions a connection. The COPY client-EOF ERROR branch detects that the client socket is already gone; it does not establish a reusable socket or a path for sending ROLLBACK. The FATAL variant closes the backend as part of the COPY-to-stdout path. The selected batch has no natural 08006 run, so these distinctions come from fixed source paths and the documented transaction boundary rather than a synthetic socket experiment.

Representative case

This page has no selected natural SQL run. The structured evidence records a source or definition boundary; a client-side RAISE would not represent a backend mechanism.

Versions

The generated facts table records the locked catalogue snapshots and earliest observed definition. This page has no selected natural SQL run; its fixed REL_18_6/REL_10_23 source boundary must not be read as an observed runtime result or as a claim about every intermediate release.

Sources

  • src.fdw-connection-failure.18.6 — contrib/postgres_fdw/connection.c at REL_18_6 commit 724edf9bde9d356724ad384a2e196edc3c9f80f7; fixed blob SHA-256 67fc002657f2c7df6d93cbf99c933cbc103907d1857ed77aedbb85099ea4dda0 (source).
  • src.copy-connection-failure.10.23 — src/backend/commands/copy.c at REL_10_23 commit 02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4; fixed blob SHA-256 0edb032be1ce8d8c90efc28e504aa9e298a2cd26cd374c85da6da0e33ed0915c (source).
  • src.copy-client-eof.18.6 — src/backend/commands/copyfromparse.c at REL_18_6 commit 724edf9bde9d356724ad384a2e196edc3c9f80f7; fixed blob SHA-256 bc42754023579cd782a3cb3f144ad2c2c3d3aa46119eb7567fcdb05f2d445571 (source).
  • src.copy-client-eof.10.23 — src/backend/commands/copy.c at REL_10_23 commit 02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4; fixed blob SHA-256 0edb032be1ce8d8c90efc28e504aa9e298a2cd26cd374c85da6da0e33ed0915c (source).
  • src.calls.REL_18_6 / src.calls.REL_10_23 — fixed local call scans, SHA-256 9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf / 00d16d3eb01b71ccf1b245c8f3102f9d0ec9f36fb02777b8dd1b99fcb263040c; these scans preserve the resolved call context used by the claims.

Source evidence

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

08006 is the connection_failure condition in Class 08.

Method: Read the fixed errcodes.txt definition and the locked catalogue metadata.

Limits: Directory identity does not identify every backend or client path.

src.errcodes.18.6

The fixed source paths resolve 08006 to distinct established-connection failure branches: postgres_fdw cancel warnings, a COPY-to-stdout FATAL in REL_10_23, and COPY client-EOF ERROR paths in REL_18_6 and REL_10_23. The exact diagnostic and severity depend on where the connection loss is detected.

Method: Trace the fixed REL_18_6 and REL_10_23 source call scans and the recorded source paths.

Limits: This is a bounded source claim; this batch has no selected natural 08006 runtime, and it does not claim that an ordinary client socket failure exposes this SQLSTATE.

src.fdw-connection-failure.18.6 src.copy-connection-failure.10.23 src.copy-client-eof.18.6 src.copy-client-eof.10.23

The fixed 08006 variants have different recovery contracts: the COPY client-EOF ERROR detects that the triggering client socket is already at EOF and therefore does not establish a reusable session for sending ROLLBACK; an independently still-connected ERROR can require rollback or savepoint recovery, while FATAL ends the backend; a client EOF without an ErrorResponse may expose no SQLSTATE.

Method: Combine the COPY client-EOF source branch, recorded source severities, and the official transaction and savepoint recovery contract.

Limits: This is a source-backed boundary; the COPY EOF branch says nothing about reusing the already-lost client socket, and this batch selected no natural 08006 runtime or ordinary socket failure.

mechanism.source-boundary doc.transactions.18

The locked catalogue records 08006 in the listed snapshots; this page compares only the fixed REL_18_6 and REL_10_23 source paths and has no selected natural runtime.

Method: Read the generated facts block and fixed source records; no runtime result is used for this source-only page.

Limits: Presence in a definition file is not an exact behavioral introduction, and the fixed source paths do not prove every intermediate release or socket failure.

src.errcodes.18.6 src.copy-client-eof.18.6 src.copy-client-eof.10.23

Message templates

explicit WARNING · message.fdw-cancel-send

Primary

could not send cancel request: %s

The %s value is the dynamic libpq/cancel error text.

explicit WARNING · message.fdw-cancel-result

Primary

could not get result of cancel request: %s

The %s value is the dynamic error text returned while reading the cancel result; the fixed source has more than one call site.

explicit FATAL · message.copy-connection-lost

Primary

connection lost during COPY to stdout

This exact fixed branch is recorded from REL_10_23; the page does not generalize it to every COPY direction or release.

explicit ERROR · message.copy-client-eof-open-tx

Primary

unexpected EOF on client connection with an open transaction

The fixed COPY client-EOF path reports this when an open transaction is present; the source confirms the branch, not a selected natural run in this batch.

Reproduction & repair cases

source_boundary · PG 10, 18

Preconditions

  • A runner-owned disposable target is provisioned only if a source-boundary smoke run is requested.

Trigger: No artificial SQL trigger is executed; this record preserves the fixed source/definition boundary.

Expected assertions

    Repair: Use the concrete source path or component-specific documentation when it applies.

    Cleanup: Drop the case schema with an owner connection.

    Recorded runtime evidence

    No runtime observation is attached to this entry.

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