The connection could not be established, and no structured signal exists to say why.

This is the residual case at the connection stage: DNS failure, connection refused, TLS negotiation failure, a rejected password, a missing database, and any other rejection libpq does not surface a flag for, all land here alike.

The server demanded a password and none was available.

Reported from PQconnectionNeedsPassword, a flag libpq sets from the authentication exchange rather than from message text. A wrong password, by contrast, reports False on this flag and is indistinguishable from any other connection refusal, so it lands in ConnectionAcquireError instead.

The server's version is below the minimum this driver supports.

The three fields are the server's major, minor and patch version, in that order. The minimum required version is not carried alongside them: it is a constant of this library, currently 9.0.0.

Session initialization failed and the connection died: there is prose and nothing else.

This covers both PQexec returning no result at all and PQexec returning a result libpq fabricated client-side with no diagnostic fields on it - the same event either way, distinguished from InitializationServerErrorAcquireError by whether the result carries a SQLSTATE, not by whether a result exists.

Session initialization failed and the server said why.

The server rejected the initialization statement and returned a real error report, readable through PQresultErrorField. This is the one AcquireError for which toSqlState can return Just.

The session reported an ordinary failure and the connection is still usable.

The connection is gone.

This covers every way use can lose the connection: a dropped socket, a request libpq refused to send outright (e.g. more than 65535 parameters in one statement), an unexpected response from the server, or a bug in Hasql. The reason text says which.

use has finished the connection before returning this, so the Connection the session ran on is spent: further use on it fails with this same error, and release is a no-op. Pools must discard it rather than return it.

Whatever the cause, the driver cannot vouch for the protocol state of a connection a request failed to leave, and repairing one costs more than replacing it: the repair would have to push a Sync, which flushes and commits the very commands the failed session never got to complete. So this is reported uniformly rather than split by cause - retry policy belongs to the caller, informed by the reason text and, for server errors, toSqlState.

An error occurred while executing a statement in the session.

This wraps statement-level errors and provides additional context about:

• Which statement in the pipeline failed (when multiple statements are batched)
• The SQL text and parameters of the failing statement
• Whether the statement was prepared or unprepared

The error message includes formatted output showing all this context, making it easier to diagnose issues in production.

An error occurred while executing a script.

Scripts are multi-statement SQL texts executed via script. Unlike regular statements, scripts don't support parameters or result decoding, and errors are limited to server-reported issues.

One or more types referenced in the statement could not be found in the database.

This occurs when using custom types (enums, composite types, domains) that are resolved by name at runtime, but the types don't exist in the database.

To fix this error:

• Ensure the types are defined in the database
• Check that schema search paths are configured correctly
• Verify that the type names in your code match those in the database

The server rejected the statement and returned an error.

This includes SQL syntax errors, constraint violations, permission errors, and any other error reported by PostgreSQL during statement execution.

The statement returned a different number of rows than expected.

This occurs when using result decoders like Decoders.singleRow or Decoders.rowsAffectedAtLeast that have specific row count expectations.

The statement returned a different number of columns than expected.

This indicates a mismatch between the decoder specification and the actual result structure, possibly due to:

• Schema changes (columns added or removed)
• Wrong query (selecting different columns than expected)
• Decoder configuration error

A column has a different type than expected.

This occurs when the decoder expects a specific PostgreSQL type (by OID) but the actual column has a different type. This can happen due to:

• Schema changes (column type changed)
• Wrong query (selecting wrong column or using a cast)
• Decoder configuration error

Note: As of version 1.10, Hasql performs strict type checking and will report this error instead of attempting automatic type coercion.

An error occurred while decoding a specific row.

This wraps errors that occur at the row or cell level, providing context about which row failed.

The database returned an unexpected result structure.

This is a catch-all error that indicates either:

• An improper statement (e.g., executing a query that doesn't match expectations)
• A schema mismatch between the code and database
• A bug in Hasql or server misbehavior

An error occurred while decoding a specific cell in the row.

This wraps cell-level errors (null handling, deserialization failures) and provides context about which column failed and its type.

A refinement or validation error when processing the row.

This occurs when using refinement functions in row decoders (e.g., with refineRow) to validate or transform decoded values. The refinement function rejected the row data.

A NULL value was encountered when a non-NULL value was expected.

This occurs when using non-nullable decoders (e.g., Decoders.nonNullable) on a column that contains a NULL value.

Failed to deserialize the cell value from its binary representation.

This can occur when:

• The binary data is corrupted
• The decoder doesn't match the actual data type
• The data format is invalid for the expected type