Table of contents

• Authentication errors:

  • Database
  • Client
  • ZeroKMS

• Mapping errors:

  • Invalid parameter
  • Invalid SQL statement
  • Unsupported parameter type
  • Statement could not be type checked
  • Unmappable encrypted column
  • Internal Error

• Encrypt errors:

  • Invalid encrypted value
  • Column could not be encrypted
  • Could not decrypt data for keyset
  • KeysetId could not be parsed
  • KeysetId could not be set
  • KeysetName could not be set
  • Plaintext could not be encoded
  • Unknown column
  • Unknown Keyset Identifier
  • Unknown table
  • Unknown index term
  • Column configuration mismatch
  • Missing encrypt configuration
  • Unexpected SET keyset
  • Encrypted jsonb column configured for ORE ordering

• Decrypt errors:

  • Column could not be deserialised
  • Encrypted jsonb value has no root entry
  • Encrypted jsonb entry has an invalid selector

• Configuration errors:

  • Missing or invalid TLS configuration
  • Network configuration change requires restart

Internal PostgreSQL protocol error

CipherStash Proxy encountered an unexpected internal protocol state while processing a PostgreSQL response.

Error message

CipherStash Proxy encountered an internal PostgreSQL protocol error.

How to fix

Retry the operation. If the error persists, collect the proxy logs and report the issue to CipherStash support. The logs retain the detailed internal error needed for diagnosis.

Authentication errors

Database

Authentication failed when connecting to the database.

Error message

Database authentication failed. Check username and password

How to fix

1. Check the configured username and password are correct and can connect to the database.

2. Check the database is using a supported authentication method.

CipherStash Proxy supports several PostgreSQL password authentication methods:

• password
• md5
• scram-sha-256

See PostgreSQL password authentication

Client

Authentication failed when connecting a client to the proxy.

Error message

Client authentication failed. Check username and password.

How to fix

1. Check the configured username and password are correct.

ZeroKMS

Authentication failed when connecting to ZeroKMS.

Error message

ZeroKMS authentication failed. Check the configured credentials.

How to Fix

1. Check that the configured client credentials are correct.
2. Check that the active keyset_name or keyset_id is associated with a keyset in the configured workspace.

Mapping errors

Invalid parameter

The column parameter value is not of the correct cast type for the target encrypted column.

Error message

Invalid parameter for column 'column_name' of type 'cast' in table 'table_name'. (OID 'oid')

Notes

An encrypted column definition includes the target cast type of the data to be stored.

To encrypt a statement parameter or literal, CipherStash Proxy decodes and casts the data into the target type.

The error indicates that the passed data cannot be decoded and cast into the expected type.

In some cases, parameter types can be converted. For example PostgreSQL INT2, INT4 and INT8 will all be converted into encrypted SmallInt, Int, or BigInt types.

How to fix

Check the parameter or literal is of the appropriate type for the configured encrypted column.

Invalid SQL Statement

The SQL statement could not be parsed.

Error message

Error messages will vary depending on the specific syntax error in the sql statement provided.

   sql parser error: Expected: SELECT, VALUES, or a subquery in the query body

Notes

As SQL is a vast, sprawling language, the proxy may fail to parse some valid SQL statements. Please contact CipherStash if you think your SQL is correct and the parser is wrong.

How to fix

Check the SQL is a valid PostgreSQL SQL statement.

Unsupported Parameter type

The parameter type is not supported.

Error message

Encryption of EQL column {column_type} using strategy {eql_term} is not supported.

How to fix

Check the supported types for encrypted columns.

Statement could not be type checked

An error occurred when attempting to type check the SQL statement.

Error message

Statement could not be type checked: '{type-check-error-message}'

Notes

CipherStash Proxy checks SQL statements against the database schema to transparently encrypt and decrypt data.

The behaviour of Proxy depends on the mapping_errors_enabled configuration.

When mapping_errors_enabled is false (the default), then type check errors are logged, and the statement is passed through to the database.

When mapping_errors_enabled is true, then type check errors are raised, and statement execution halts.

Configure this setting with the environment variable CS_DEVELOPMENT__ENABLE_MAPPING_ERRORS or in the TOML config file under [development] enable_mapping_errors = true.

In our experience, most production systems have a relatively small number of columns that require protection. As SQL is large and complex, instead of blocking statements with type check errors that are false negatives, the default behaviour of Proxy is to allow the statement.

However, this does mean it is possible that a statement that references encrypted columns cannot be type-checked, and it will be passed through to the database. When a statement is passed through to the database, the database's column constraints (provided by EQL) will catch the statement, and return a PostgreSQL error.

Example constraint error:

ERROR:  Encrypted column missing version (v) field: 34234
CONTEXT:  PL/pgSQL function _cs_encrypted_check_v(jsonb) line 6 at RAISE
SQL function "cs_check_encrypted_v1" statement 1

How to fix

In most cases, this error will occur if the statement contains invalid or unsupported syntax.

Check if you are running the latest version of CipherStash Proxy, and update to the latest version if not.

If the error persists, please contact CipherStash support.

Unmappable encrypted column

A table referenced by the statement has a column declared with the legacy EQL v2 eql_v2_encrypted type. This version of Proxy targets EQL v3 and cannot encrypt or decrypt that type, so it refuses the statement rather than serve the column.

Error message

Column '{table}.{column}' is declared as 'eql_v2_encrypted', a legacy EQL v2 type that this
version of CipherStash Proxy cannot encrypt or decrypt. Statements referencing '{table}' are
refused so that plaintext is never written to the column. Migrate '{table}.{column}' to an
EQL v3 domain type.

Notes

This is the signature of a partly-completed EQL v2 to v3 migration: most columns moved to v3 domain types, and one was left behind.

Proxy identifies encrypted columns by their type. An EQL v3 encrypted column is a jsonb-backed domain whose name encodes its scalar type and searchable capabilities (eql_v3_text_search, eql_v3_integer_ord, and so on). EQL v2's eql_v2_encrypted carries none of that information, so Proxy has no way to encrypt a value written to such a column, and no way to decrypt one read back.

Every statement referencing the table is refused, not only those naming the column. This is deliberate. A statement can reach a column it never names — through SELECT *, column defaults, RETURNING, triggers or rules — and getting that analysis wrong would mean writing plaintext into a column you believe is encrypted. Refusing on the table needs no such analysis. Other tables are unaffected, and Proxy continues to serve them normally.

Unlike a type-check failure, this refusal is not subject to the mapping_errors_enabled passthrough. That fallback exists for statements Proxy does not understand, on the reasoning that they probably touch nothing encrypted. Here Proxy understands the statement exactly, and forwarding it is the specific harm the error exists to prevent, so the statement is refused whatever CS_DEVELOPMENT__ENABLE_MAPPING_ERRORS is set to.

Proxy also logs a warning naming each such column when it loads the schema at startup.

How to fix

Migrate the column to the EQL v3 domain type matching the data it holds and the operations you run against it — for example eql_v3_text_search for searchable text, or eql_v3_integer_ord for an orderable integer. Existing v2 ciphertext must be decrypted and re-encrypted as part of that migration; it cannot be reinterpreted in place.

If the column is no longer used, dropping it also resolves the error.

Internal Mapper error

An internal error occurred when attempting to type check or transform a SQL statement. This could be due to an internal invariant failure, or because of a specific fragment of unsupported SQL syntax.

Error message

Statement encountered an internal error. This may be a bug in the statement mapping module of CipherStash Proxy.

How to fix

Check if you are running the latest version of CipherStash Proxy, and update to the latest version if not.

If the error persists, please contact CipherStash support.

Encrypt errors

Invalid encrypted value

CipherStash Proxy rejected an application-generated EQL storage payload or query operand because it was malformed, unauthentic, intended for another column, carried unexpected searchable encrypted metadata (SEM), or appeared in an invalid statement position. The response deliberately does not identify which validation failed.

Error message

Invalid encrypted value. For help visit https://github.com/cipherstash/proxy/blob/main/docs/errors.md#encrypt-invalid-inbound-eql-payload

How to fix

Regenerate the payload using the same column configuration, keyset, and credentials as Proxy. Storage payloads must target the inferred destination column and carry ciphertext plus exactly its configured SEM terms. Query-only payloads must be used only in query positions.

Plaintext compatibility

On every encrypted column type, Proxy reserves three JSON object shapes for application-generated EQL:

• a storage payload with top-level v and i keys plus at least one of c, h, or sv;
• a scalar query payload with top-level v and i keys plus at least one of hm, bf, ob, or op; or
• a SteVec query payload whose only top-level key is sv.

An object matching one of these patterns is validated as EQL rather than encrypted as plaintext. Invalid EQL is rejected, and query-only payloads are rejected in storage positions. There is no opt-out for this fail-closed check.

Before upgrading, audit JSON values supplied as plaintext to encrypted columns. For a jsonb source column named value, this predicate identifies all three reserved shapes:

WHERE CASE
  WHEN jsonb_typeof(value) <> 'object' THEN false
  ELSE (
    value ? 'v'
    AND value ? 'i'
    AND value ?| ARRAY['c', 'h', 'sv', 'hm', 'bf', 'ob', 'op']
  ) OR (
    value ? 'sv'
    AND NOT EXISTS (
      SELECT 1
      FROM jsonb_object_keys(value) AS keys(candidate_key)
      WHERE candidate_key <> 'sv'
    )
  )
END

For text sources, first restrict the scan to values that your application knows are valid JSON, then apply the same predicate after casting them to jsonb. Rename one of these top-level keys or generate the value as an EQL payload before sending it through Proxy.

Column could not be encrypted

The column could not be encrypted.

Error message

Column 'column_name' in table 'table_name' could not be encrypted.

Notes

CipherStash Proxy uses CipherStash ZeroKMS for low-latency encryption and decryption operations.

The error indicates an issue has occurred in the encryption pipeline processing. The most likely cause is network access to the ZeroKMS service.

How to Fix

1. Check that CipherStash ZeroKMS is available at the status page.
2. Check that CipherStash Proxy has network access to ZeroKMS in the appropriate region.

3. Check that the encrypted configuration cast matches the expected type.

KeysetId could not be parsed

A keyset_id could not be parsed using the SET CIPHERSTASH.KEYSET_ID command.

Error message

KeysetId `{id}` could not be parsed using `SET CIPHERSTASH.KEYSET_ID`. KeysetId should be a valid UUID.

How to Fix

1. Check that the KeysetId is a valid UUID.

   SET [ SESSION ] CIPHERSTASH.KEYSET_ID { TO | = } '{KeysetId}'

KeysetId could not be set

A KeysetId could not be set using the SET CIPHERSTASH.KEYSET_ID command.

Error message

Keyset Id could not be set using `SET CIPHERSTASH.KEYSET_ID`

How to Fix

1. Check the syntax of the SET CIPHERSTASH.KEYSET_ID command. The keyset_id value should be in single quotes.
2. Check that the keyset_id is a valid UUID.
3. Check that the value is being set as a literal. The PostgreSQL SET statement does not support parameterised querying.

   SET [ SESSION ] CIPHERSTASH.KEYSET_ID { TO | = } '{keyset_id}'

KeysetName could not be set

KeysetName could not be set using the SET CIPHERSTASH.KEYSET_NAME command.

Error message

Keyset Name could not be set using `SET CIPHERSTASH.KEYSET_NAME`

How to Fix

1. Check the syntax of the SET CIPHERSTASH.KEYSET_ID command. The keyset_name value should be in single quotes.
2. Check that the value is being set as a literal. The PostgreSQL SET statement does not support parameterised querying.

   SET [ SESSION ] CIPHERSTASH.KEYSET_NAME { TO | = } '{keyset_name}'

Unknown keyset identifier

The specified keyset could not be loaded.

Error message

Unknown keyset name or id '{keyset}'

How to Fix

1. Check that the active keyset_name or keyset_id is associated with a keyset in the configured workspace.
2. Check that the configured client has been granted access to the keyset via the dashboard.
3. Keyset names are case sensitive. If setting the active keyset by name, check that the keyset_name is an exact match.
4. Check that the configured client credentials are correct.

Could not decrypt data for keyset

The data belonging to the active keyset_id could not be decrypted.

Error message

Could not decrypt data for keyset '{keyset_id}'

Notes

This error is caused because the active keyset_id does not match the keyset_id of the data being decrypted.

Each encrypted record belong to a keyset with a unique identifier (the keyset_id).

The proxy encrypts data in the currently active keyset.

A single default keyset can be defined in the proxy configuration or the SET CIPHERSTASH.KEYSET_ID statement can be used to dynamically set the active keyset at runtime.

If the keyset_id of the record does not match the current keyset_id the data cannot be decrypted.

How to Fix

1. Check that the keyset_id in the configuration matches the keyset_id of the encrypted records.
2. If using the SET CIPHERSTASH.KEYSET_ID statement, check that this keyset_id matches the keyset_id of the encrypted records.
3. Check that the configured client has been granted access to the keyset_id.

Plaintext could not be encoded

The encrypted data in a column returned by a SQL statement cannot be encoded into the correct type.

Error message

Decrypted column could not be encoded as the expected type.

Notes

An encrypted column definition includes the target cast type of the data to be stored.

Encrypted data is stored as the raw (encrypted) bytes in the database.

When a statement returns encrypted data, CipherStash Proxy decrypts the data, casts, and encodes as the PostgreSQL representation of the target type.

The error indicates that the stored data cannot be encoded and returned as the expected type.

Changing the encrypted column definition of a column with existing data can cause this error.

For example:

• column is defined with a cast of text
• data is encrypted and stored as text
• column is redefined with a cast of int
• error as existing records stored as text data cannot be decrypted, cast and encoded as int

How to fix

1. Check the encrypted configuration has the correct type.
2. Check that the configuration has not changed.
3. Check EQL.

Unknown Column

The column has an encrypted type (an EQL v3 encrypted domain type, e.g. eql_v3_text_search) with no encryption configuration.

Without the configuration, Cipherstash Proxy does not know how to encrypt the column. Any data is unprotected and unencrypted.

Error message

Column 'column_name' in table 'table_name' has no Encrypt configuration

How to fix

1. Define the encrypted configuration using EQL.
2. Add users.email as an encrypted column:

   SELECT cs_add_column_v1('users', 'email');
   

Unknown Table

The table has one or more encrypted columns (an EQL v3 encrypted domain type, e.g. eql_v3_text_search) with no encryption configuration.

Without the configuration, Cipherstash Proxy does not know how to encrypt the column. Any data is unprotected and unencrypted.

Error message

Table 'table_name' has no Encrypt configuration

How to fix

1. Define the encrypted configuration using EQL.
2. Add users.email as an encrypted column:

   SELECT cs_add_column_v1('users', 'email');
   

Unknown Index Term

The encrypted column has an unknown index configuration.

EQL validates indexes when they are added to ensure that the configuration is correctly defined. However, if the configuration is changed directly in the database, it is possible to misconfigure the setup.

Error message

Unknown Index Term for column '{column_name}' in table '{table_name}'.

How to fix

1. Check the Encrypt configuration for the column.
2. Define the encrypted configuration using EQL.

Column configuration mismatch

A returned encrypted column does not match the column configuration.

Error message

Column configuration for column '{column_name}' in table '{table_name}' does not match the encrypted column.

Notes

CipherStash Proxy validates that encrypted columns match the configuration before decrypting any data. If the table and column are not the same, this error is returned. The check is there to help prevent "confused deputy" issues and the error should never appear during normal operation.

If the error persists, please contact CipherStash support.

Further reading

AWS: The confused deputy problem Wikipedia: Confused deputy problem

Missing encrypt configuration

The encrypted column type does not have a matching encrypt configuration.

Error message

Missing encrypt configuration for column type `{plaintext_type}`.

How to fix

1. Define the encrypted configuration for the column type using EQL.
2. If this error persists, please contact CipherStash support as this may indicate a bug.

Unexpected SET keyset

A SET CIPHERSTASH.KEYSET statement was used when a default keyset has already been configured.

Error message

Cannot SET CIPHERSTASH.KEYSET if a default keyset has been configured.

How to fix

1. Remove the SET CIPHERSTASH.KEYSET statement from your application code.
2. Or remove the default_keyset_id from the proxy configuration to allow dynamic keyset selection.

Encrypted jsonb column configured for ORE ordering

An encrypted jsonb (SteVec) column is configured for Standard-mode ORE ordering, which EQL v3 does not support.

EQL v3 orders encrypted jsonb entries by the CLLW-OPE (op) term and has no representation for CLLW-ORE (oc). A column carried over from an earlier configuration that used ORE ordering therefore cannot be encrypted under EQL v3.

Error message

An encrypted jsonb column is configured for ORE ordering, which EQL v3 does not support.

How to fix

1. Reconfigure the column to use a supported ordering mode.
2. Re-encrypt the column's data under the new configuration.

Decrypt errors

Column could not be deserialised

The column could not be deserialised for decryption.

Error message

Column 'column_name' in table 'table_name' could not be deserialised.

Notes

CipherStash Proxy stores encrypted data and search terms as jsonb. The structure is defined as part of EQL.

The error indicates an internal issue has occurred deserialising and extracting the ciphertext data for decryption. It may be caused if the the encrypted data has been altered by another process or application.

If the error persists, please contact CipherStash support.

How to Fix

1. Check that the data in the encrypted column is in the correct format EQL.

Encrypted jsonb value has no root entry

An encrypted jsonb (SteVec) value has an empty sv array and cannot be decrypted.

The first entry of a SteVec document (sv[0]) is its decryption root. A document with no entries has nothing to decrypt, which indicates the stored value has been truncated or altered by another process.

Error message

Encrypted jsonb value has no root entry and cannot be decrypted.

How to fix

1. Check that the data in the encrypted column has not been modified outside CipherStash Proxy.
2. If the error persists, please contact CipherStash support.

Encrypted jsonb entry has an invalid selector

An encrypted jsonb (SteVec) entry has a selector that is not exactly 16 hex-encoded bytes.

A SteVec entry's selector is the source of both AEAD bindings (nonce and AAD), so it must be exactly 16 hex-encoded bytes. A selector of any other length indicates the stored value has been altered by another process.

Error message

Encrypted jsonb entry has an invalid selector '{selector}'.

How to fix

1. Check that the data in the encrypted column has not been modified outside CipherStash Proxy.
2. If the error persists, please contact CipherStash support.

Configuration errors

Database

There was a problem with the Tls configuration.

Error message

# PEM-based configuration
Invalid Transport Layer Security (TLS) certificate.
Invalid Transport Layer Security (TLS) private key.

# Path-based configuration
Missing Transport Layer Security (TLS) certificate at path: {path}.
Missing Transport Layer Security (TLS) private key at path: {path}.

How to fix

If using path-based configuration: Check that the certificate and private key exists at the specified path. Check that the certificate and private key are valid.

If using PEM-based configuration: Check that the certificate and private key are valid.

Network configuration change requires restart

A configuration reload was attempted with network-level changes that require a full restart.

Error message

Network configuration change requires restart

Notes

When receiving a SIGHUP signal, CipherStash Proxy attempts to reload application-level configuration without disrupting active connections. However, certain network-related configuration changes require stopping and restarting the proxy service to take effect.

The following settings require a restart when changed:

• server.host - The host address the proxy listens on
• server.port - The port the proxy listens on
• server.require_tls - TLS requirement setting
• server.worker_threads - Number of worker threads
• tls - Any TLS certificate or key configuration

How to fix

1. Stop the CipherStash Proxy service
2. Update the configuration as needed
3. Restart the CipherStash Proxy service

Application-level configuration changes (database, auth, encrypt, log, prometheus, development) can be reloaded without restart using SIGHUP.