Network-level error while connecting to the database server.

This typically indicates issues like:

• Server is not reachable (wrong host/port or server is down)
• Network connectivity problems
• Firewall blocking the connection
• Connection timeout

These errors are transient and the operation can be retried.

Authentication failed when connecting to the database.

This typically indicates issues like:

• Invalid username or password
• User does not have permission to access the database
• Authentication method mismatch (e.g., server requires SSL but client doesn't use it)

These errors are not transient and require fixing the credentials or permissions.

Compatibility issue between client and server.

This typically indicates issues like:

• Server version is too old or too new
• Required PostgreSQL features are not available
• Protocol version mismatch

These errors are not transient and require upgrading/downgrading the server or client.

Uncategorized error coming from libpq.

This is a catch-all for connection errors that don't fit into other categories. The error message may be empty if libpq doesn't provide details.

These errors are not transient by default.

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.

A connection-level error occurred during session execution.

This indicates that the connection to the database was lost or became unusable during the session. These errors are transient and the operation can be retried with a new connection.

Note: As of version 1.10, connections recover from async exceptions without resetting, preserving connection-local state.

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

An internal driver error occurred.

This indicates either:

• A bug in Hasql
• The PostgreSQL server misbehaving
• An unexpected response from the server

If you encounter this error, please report it as a bug.

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