clickhouse

ClickHouse Error Codes

Numeric server error codes returned by ClickHouse. Each code has a symbolic name (e.g. BAD_ARGUMENTS, UNKNOWN_TABLE) and is surfaced in error messages and system tables.

72 codes

references clickhouse.com/docs/en/operations/error-codes

· All codes 72 codes

ACCESS_DENIED Access denied The current user does not have the privilege required to perform the requested operation. Grant the necessary privilege or connect with a higher-privileged account.
AMBIGUOUS_COLUMN_NAME Ambiguous column name A column name referenced in the query exists in more than one joined table without a qualifying table alias. Add a table prefix to disambiguate.
BAD_ARGUMENTS Bad arguments One or more arguments supplied to a function or command are invalid, out of range, or of the wrong type. Review the function signature and argument values.
CANNOT_COMPRESS Cannot compress Data compression failed, typically due to insufficient memory or an unsupported codec configuration. Check the codec settings and available memory.
CANNOT_CONNECT_TO_ZOOKEEPER Cannot connect to ZooKeeper The server failed to establish or lost a connection to ZooKeeper (or ClickHouse Keeper), which is required for ReplicatedMergeTree coordination. Check Keeper availability and connection configuration.
CANNOT_DECOMPRESS Cannot decompress Decompression of a data block failed, which usually indicates corrupt data on disk or a mismatch between the compression codec used to write and read the data.
CANNOT_OPEN_FILE Cannot open file The server failed to open a file, typically due to a missing path, insufficient permissions, or a filesystem error. Check the file path and server process permissions.
CANNOT_PARSE_DATE Cannot parse date A string value could not be interpreted as a valid date. Ensure the format matches the expected pattern (YYYY-MM-DD) or use an explicit `toDate` conversion.
CANNOT_PARSE_DATETIME Cannot parse datetime A string value could not be interpreted as a valid DateTime. Verify the format and timezone, or use `parseDateTimeBestEffort` for flexible parsing.
CANNOT_PARSE_NUMBER Cannot parse number A string value could not be parsed as a number during data ingestion or type conversion. Check the input data for non-numeric characters.
CANNOT_PARSE_TEXT Cannot parse text The server failed to parse a value from its text representation, such as an invalid date string or a non-numeric character in a numeric column.
CANNOT_READ_ALL_DATA Cannot read all data The server could not read the expected number of bytes from the data source. This typically signals a truncated file, a corrupt block, or an abrupt connection close.
CANNOT_WRITE_TO_FILE_DESCRIPTOR Cannot write to file descriptor A write to a file descriptor failed, which may indicate a full disk, a broken pipe, or a closed socket. Check available disk space and network connectivity.
CHECKSUM_DOESNT_MATCH Checksum doesn't match The checksum of a data block does not match the expected value, indicating data corruption on disk or during transmission. The affected part may need to be dropped and re-fetched.
COLUMN_SPECIFIED_MORE_THAN_ONCE Column specified more than once The same column name appears more than once in a CREATE TABLE or INSERT column list. Each column must be listed exactly once.
DATABASE_ALREADY_EXISTS Database already exists A CREATE DATABASE statement attempted to create a database that already exists. Use `CREATE DATABASE IF NOT EXISTS` to suppress this error.
DISTRIBUTED_CONNECTION_FAILURE Distributed connection failure All connection attempts to remote shards in a Distributed table query failed. Check shard availability and the `remote_servers` configuration.
DUPLICATE_COLUMN Duplicate column A CREATE TABLE or SELECT statement produced duplicate column names in the output. Rename the columns using aliases to make each name unique.
ILLEGAL_COLUMN Illegal column A column is used in a context where it is not permitted, such as referencing a non-aggregate column outside a GROUP BY clause without an aggregate function.
ILLEGAL_TYPE_OF_ARGUMENT Illegal type of argument A function received an argument of an unsupported or unexpected data type. Check the function's documentation for the accepted argument types.
INTERSERVER_SCHEME_DOESNT_MATCH Interserver scheme doesn't match A replication request was made over a scheme (HTTP vs HTTPS) that does not match the receiving server's interserver configuration. Align the `interserver_http_host` settings across replicas.
LIMIT_EXCEEDED Limit exceeded A configurable query limit (such as `max_rows_to_read` or `max_bytes_to_read`) was exceeded. Adjust the limit settings or rewrite the query to read less data.
LOGICAL_ERROR Logical error An internal assertion failed, indicating a programming error in ClickHouse itself. File a bug report with the server version and the full stack trace from the logs.
MEMORY_LIMIT_EXCEEDED Memory limit exceeded Query or server memory usage exceeded the configured limit (`max_memory_usage` or `max_server_memory_usage`). Optimise the query, reduce result set size, or increase the limit.
NETWORK_ERROR Network error A network-level error occurred during a query, such as a broken connection between nodes in a distributed query. Check inter-node connectivity and firewall rules.
NO_REPLICA_HAS_PART No replica has part A data part needed for a replicated merge or fetch is not available on any live replica. This can occur after data loss or misconfiguration; manual intervention may be required.
NO_SUCH_COLUMN_IN_TABLE No such column in table An ALTER TABLE or INSERT statement references a column that does not exist in the table. Check the column name against the current table schema.
NO_ZOOKEEPER No ZooKeeper A replicated operation requires ZooKeeper (or ClickHouse Keeper) but none is configured. Add a `<zookeeper>` section to the server configuration.
NOT_ENOUGH_SPACE Not enough space The server ran out of disk space while writing data. Free disk space or configure additional storage volumes.
NOT_IMPLEMENTED Not implemented The requested feature or code path has not been implemented in this server version. Consider upgrading ClickHouse or using an alternative approach.
NUMBER_OF_ARGUMENTS_DOESNT_MATCH Number of arguments doesn't match A function was called with the wrong number of arguments. Consult the function documentation for the required arity.
NUMBER_OF_COLUMNS_DOESNT_MATCH Number of columns doesn't match The number of columns in an INSERT or SELECT statement does not match the table schema or the SELECT target list. Align the column counts on both sides.
PART_IS_TEMPORARILY_LOCKED Part is temporarily locked A data part is locked by an ongoing merge, mutation, or fetch and cannot be accessed. Retry the operation after the background task completes.
POCO_EXCEPTION Poco exception An exception from the Poco networking/utility library was propagated to the query layer. The accompanying message provides the specific Poco error detail.
QUERY_IS_TOO_LARGE Query is too large The query text exceeds the `max_query_size` limit. Simplify the query or increase the limit in server configuration.
QUERY_WAS_CANCELLED Query was cancelled The query was cancelled, either by the client, by a KILL QUERY statement, or because the timeout was exceeded. Re-run the query if the cancellation was unintentional.
READONLY Readonly The query attempts a write operation but the server or session is in read-only mode. Change the `readonly` setting or connect to a writable replica.
REPLICA_IS_ALREADY_ACTIVE Replica is already active An attempt was made to activate a replica that is already marked as active in ZooKeeper. This may indicate a duplicate process or a stale ZooKeeper node.
REPLICA_IS_NOT_IN_QUORUM Replica is not in quorum An INSERT with `insert_quorum` set could not achieve the required number of replica acknowledgements within the timeout. Check replica health and network connectivity.
REQUIRED_PASSWORD Required password The server requires a password for this user but none was provided in the connection request. Supply credentials in the connection string or client configuration.
SOCKET_TIMEOUT Socket timeout A network socket operation timed out, typically during a distributed query or when reading from a remote table. Increase `connect_timeout` / `receive_timeout` or investigate node health.
STD_EXCEPTION Std exception A C++ standard library exception was thrown and propagated to the query layer. The accompanying message provides the specific exception detail.
SYNTAX_ERROR Syntax error The query could not be parsed due to a syntax error. The error message includes the position and the token that caused the failure.
TABLE_ALREADY_EXISTS Table already exists A CREATE TABLE statement attempted to create a table whose name already exists in the database. Use `CREATE TABLE IF NOT EXISTS` or drop the existing table first.
TABLE_IS_DROPPED Table is dropped The table referenced in the query has been dropped and is no longer accessible. Recreate the table or restore it from a backup.
TABLE_SIZE_EXCEEDS_MAX_DROP_SIZE_LIMIT Table size exceeds max drop size limit A DROP TABLE was rejected because the table is larger than the `max_table_size_to_drop` limit. Set the limit to 0 or create a flag file to bypass this safety check.
THERE_IS_NO_COLUMN There is no column A referenced column does not exist in the target table during an INSERT or ALTER operation. Verify the column list matches the table schema.
TIMEOUT_EXCEEDED Timeout exceeded Query execution exceeded the time limit configured by `max_execution_time`. Optimise the query or increase the timeout setting.
TOO_DEEP_RECURSION Too deep recursion Recursive query evaluation or subquery nesting exceeded the server's configured depth limit. Simplify the query or increase `max_ast_depth`.
TOO_LARGE_SIZE_COMPRESSED Too large size compressed A compressed data block exceeds the maximum allowed size, which may indicate corrupt data or a configuration mismatch between writer and reader.
TOO_MANY_PARTS Too many parts A MergeTree table has accumulated more parts than the configured limit, usually due to an excessive INSERT rate that outpaces background merges. Slow down inserts or tune merge settings.
TOO_MANY_SIMULTANEOUS_QUERIES Too many simultaneous queries The number of concurrently executing queries reached the server limit set by `max_concurrent_queries`. Retry after existing queries complete or increase the limit.
TOO_SLOW Too slow Query execution speed fell below the minimum threshold configured by `min_execution_speed`. The query was aborted to prevent resource exhaustion.
TYPE_MISMATCH Type mismatch An expression or value has an incompatible data type in the context where it is used. Add an explicit CAST or fix the expression types.
UNEXPECTED_END_OF_FILE Unexpected end of file The input stream ended before a complete data block or query was received. This often indicates a truncated file or a network interruption.
UNEXPECTED_PACKET_FROM_CLIENT Unexpected packet from client The server received a packet from the client that does not conform to the ClickHouse native protocol. This may indicate a protocol version mismatch or a malformed client implementation.
UNEXPECTED_PACKET_FROM_SERVER Unexpected packet from server The client received a packet from the server that does not conform to the ClickHouse native protocol. This may indicate a protocol version mismatch or a connection to the wrong port.
UNKNOWN_COLUMN Unknown column The referenced column does not exist in the table or subquery. Check the column name and the table schema.
UNKNOWN_COMPRESSION_METHOD Unknown compression method The compression codec identifier in a data block is not recognised. This may result from reading data written by a newer server version that supports additional codecs.
UNKNOWN_DATABASE Unknown database The specified database does not exist on this server. Create the database first or check for a typo in the database name.
UNKNOWN_EXCEPTION Unknown exception An exception of an unknown type was caught during query processing. Check the server logs for a stack trace and additional context.
UNKNOWN_FUNCTION Unknown function The function name used in the query does not exist or is not registered. Check the function name and whether any required plugin or codec is loaded.
UNKNOWN_IDENTIFIER Unknown identifier A column, alias, or other identifier referenced in the query does not exist in the current scope. Check for typos or missing table aliases.
UNKNOWN_SETTING Unknown setting The specified server or session setting does not exist. Check the setting name for typos and consult the settings reference for the running server version.
UNKNOWN_TABLE Unknown table The referenced table does not exist in the current database. Verify the table name and that the correct database is selected.
UNKNOWN_TYPE Unknown type The data type name used in a query or schema definition is not recognised by this server version. Check spelling and server compatibility.
UNKNOWN_USER Unknown user Authentication was attempted with a username that does not exist on the server. Verify the username or create the user account.
UNSUPPORTED_METHOD Unsupported method The requested operation or method is not implemented for this storage engine or object type. Check that the operation is supported by the table engine in use.
UNSUPPORTED_PARAMETER Unsupported parameter A parameter passed to a function, table engine, or setting is not recognised or not supported. Verify the parameter name and consult the relevant documentation.
VALUE_IS_OUT_OF_RANGE_OF_DATA_TYPE Value is out of range of data type A numeric value exceeds the minimum or maximum representable value for the target data type. Use a wider type or clamp the value before insertion.
WRONG_PASSWORD Wrong password The password supplied during authentication does not match the stored credential for this user. Check the password and any connection configuration.
ZOOKEEPER_SESSION_EXPIRED ZooKeeper session expired The ZooKeeper (or ClickHouse Keeper) session expired, causing replicated operations to fail. The replica will attempt to re-establish the session; ongoing operations may need to be retried.