# 08006 — connection_failure

> PostgreSQL SQLSTATE 08006: connection_failure, source-backed diagnosis and recovery guidance.
---

# 08006

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

<!-- BEGIN SQLSTATE FACTS: generated by scripts/generate.py; do not edit -->

| Field | Value |
| --- | --- |
| SQLSTATE | `08006` |
| Condition | `connection_failure` |
| Status | `active` |
| Known present by | `7.4` |
| Locked snapshots | `9.0.23, 9.1.24, 9.2.24, 9.3.25, 9.4.26, 9.5.25, 9.6.24, 10.23, 11.22, 12.22, 13.23, 14.24, 15.19, 16.15, 17.11, 18.6, 19beta3` |
| Macros | `ERRCODE_CONNECTION_FAILURE` |
| Aliases | `—` |

<!-- source facts: data/errcodes/08006.json -->
<!-- END SQLSTATE FACTS -->

## Meaning {#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 {#scenarios}

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

## Related {#related}

- [`08001` — sqlclient_unable_to_establish_sqlconnection](../08001/)
- [`08007` — transaction_resolution_unknown](../08007/)
- [`40003` — related condition](../40003/)

## Sources {#sources}

- `src.fdw-connection-failure.18.6` — `contrib/postgres_fdw/connection.c` at `REL_18_6` commit `724edf9bde9d356724ad384a2e196edc3c9f80f7`; fixed blob SHA-256 `67fc002657f2c7df6d93cbf99c933cbc103907d1857ed77aedbb85099ea4dda0` ([source](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/contrib/postgres_fdw/connection.c#L1462-L1464)).
- `src.copy-connection-failure.10.23` — `src/backend/commands/copy.c` at `REL_10_23` commit `02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4`; fixed blob SHA-256 `0edb032be1ce8d8c90efc28e504aa9e298a2cd26cd374c85da6da0e33ed0915c` ([source](https://github.com/postgres/postgres/blob/02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4/src/backend/commands/copy.c#L525-L527)).
- `src.copy-client-eof.18.6` — `src/backend/commands/copyfromparse.c` at `REL_18_6` commit `724edf9bde9d356724ad384a2e196edc3c9f80f7`; fixed blob SHA-256 `bc42754023579cd782a3cb3f144ad2c2c3d3aa46119eb7567fcdb05f2d445571` ([source](https://github.com/postgres/postgres/blob/724edf9bde9d356724ad384a2e196edc3c9f80f7/src/backend/commands/copyfromparse.c#L276-L303)).
- `src.copy-client-eof.10.23` — `src/backend/commands/copy.c` at `REL_10_23` commit `02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4`; fixed blob SHA-256 `0edb032be1ce8d8c90efc28e504aa9e298a2cd26cd374c85da6da0e33ed0915c` ([source](https://github.com/postgres/postgres/blob/02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4/src/backend/commands/copy.c#L587-L614)).
- `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.