ClickHouse DB::Exception: Storage engine requires parameters

The "DB::Exception: Storage engine requires parameters" error surfaces when you attempt to create a table using a storage engine that expects one or more arguments, but none were provided. ClickHouse identifies this condition with the error code STORAGE_REQUIRES_PARAMETER. Most table engines -- MergeTree, ReplicatedMergeTree, Kafka, MySQL, and others -- need specific configuration passed through the ENGINE clause, and omitting those arguments triggers this error.

Impact

When ClickHouse raises STORAGE_REQUIRES_PARAMETER, the CREATE TABLE statement fails entirely. No table is created, and any downstream processes waiting for that table will break. In automated migration scripts or infrastructure-as-code deployments, this can stall your entire pipeline until the DDL is corrected.

Common Causes

Empty parentheses or missing parentheses after the engine name -- writing ENGINE = ReplicatedMergeTree or ENGINE = ReplicatedMergeTree() when the engine needs a ZooKeeper path and replica name.
Copy-paste errors from documentation -- taking a simplified example that omits required parameters for brevity.
Confusing engine variants -- using MergeTree() syntax that works in newer ClickHouse versions but supplying it where an older version expects the legacy MergeTree(date_column, (primary_key), index_granularity) form.
Missing connection parameters for integration engines -- engines like MySQL, PostgreSQL, Kafka, or S3 all require connection strings, table names, or topic configurations.
Terraform or ORM misconfiguration -- DDL generated programmatically that leaves engine parameters as empty placeholders.

Troubleshooting and Resolution Steps

Check the full error message. ClickHouse typically tells you which engine is missing parameters:
```
DB::Exception: Storage MergeTree requires parameters: ...
```

Look up the required parameters for your engine. For example, ReplicatedMergeTree needs at minimum a ZooKeeper path and replica name:

CREATE TABLE events (
    event_date Date,
    event_id UInt64,
    payload String
) ENGINE = ReplicatedMergeTree('/clickhouse/tables/{shard}/events', '{replica}')
ORDER BY event_id;

Verify your ClickHouse version. The MergeTree family switched to a simplified syntax in version 18.16. In modern versions, MergeTree() with empty parentheses is valid as long as you specify ORDER BY. In older versions, positional parameters were required:
```
-- Legacy syntax (pre-18.16)
ENGINE = MergeTree(event_date, (event_id), 8192)

-- Modern syntax
ENGINE = MergeTree()
ORDER BY event_id
```
For integration engines, supply all connection details. A Kafka engine, for instance, requires the broker list, topic, group, and format:
```
CREATE TABLE kafka_queue (
    message String
) ENGINE = Kafka('broker:9092', 'my_topic', 'my_group', 'JSONEachRow');
```
Test your DDL in a staging environment first. Use clickhouse-client to run the CREATE TABLE statement interactively before committing it to migration scripts.
Check for macro expansion issues. If you use macros like {shard} or {replica} in Replicated engines, make sure they are defined in your server configuration. Missing macros can result in empty parameter values.

Best Practices

Always consult the official ClickHouse documentation for the engine you are using, especially after version upgrades.
Keep your DDL under version control so changes are reviewed before reaching production.
Use clickhouse-format to validate SQL syntax before execution.
When automating table creation, include integration tests that run DDL against a test ClickHouse instance.
Document your engine choices and their required parameters in your team's runbook.

Frequently Asked Questions

Q: Does MergeTree() with empty parentheses always work in modern ClickHouse?
A: Yes, starting from version 18.16, MergeTree() with empty parentheses is valid as long as you include an ORDER BY clause. The required parameters moved out of the engine declaration and into the table-level clauses.

Q: How do I know which parameters an engine expects?
A: The best source is the official ClickHouse documentation under the "Table Engines" section. You can also check the error message itself, which often hints at what is missing.

Q: I see this error in my Terraform plan. How do I fix it?
A: Review the engine_params or equivalent field in your Terraform ClickHouse provider configuration. Make sure all required arguments are filled in and not set to empty strings.

Q: Can I use default values for engine parameters?
A: Some engines have defaults for optional parameters, but required parameters must always be explicitly provided. For example, ReplicatedMergeTree always needs its ZooKeeper path and replica name.