ClickHouse DB::Exception: No replica name given

The DB::Exception: No replica name given error (code NO_REPLICA_NAME_GIVEN) is raised when you attempt to create a ReplicatedMergeTree table without providing the required replica name parameter. ClickHouse needs both a ZooKeeper path and a unique replica name to register the table in the coordination layer.

Impact

This error prevents the table from being created entirely. No data can be inserted or queried because the DDL statement fails at parse or validation time. It is a configuration-time issue with no effect on existing tables or other replicas.

Common Causes

1. Missing replica name in the engine definition -- the CREATE TABLE statement includes a ZooKeeper path but omits the second argument for the replica name.
2. Undefined macros -- the table definition uses {replica} but the macro is not defined in the server configuration, resulting in an empty value.
3. Incorrect engine syntax -- using the legacy two-argument format but accidentally providing only one string.
4. Copy-paste errors -- table DDL copied from documentation or another environment with placeholder values that were not updated.

Troubleshooting and Resolution Steps

1. Check your CREATE TABLE statement A correct ReplicatedMergeTree definition requires two arguments:

   CREATE TABLE my_table (
       id UInt64,
       data String
   ) ENGINE = ReplicatedMergeTree('/clickhouse/tables/{shard}/my_table', '{replica}')
   ORDER BY id;
   

   If the second parameter is missing or empty, you will get this error.

2. Verify macros are defined Inspect the current macro values on the server:

   SELECT * FROM system.macros;
   

   If {replica} is not listed or its value is empty, define it in the configuration:

   <!-- /etc/clickhouse-server/config.d/macros.xml -->
   <macros>
       <shard>01</shard>
       <replica>clickhouse-node-1</replica>
   </macros>
   

3. Use the default replica name feature (ClickHouse 22.3+) In newer ClickHouse versions, you can omit both arguments if default_replica_path and default_replica_name are configured in the server settings:

   <default_replica_path>/clickhouse/tables/{shard}/{database}/{table}</default_replica_path>
   <default_replica_name>{replica}</default_replica_name>
   

   With these defaults, ENGINE = ReplicatedMergeTree (no arguments) works out of the box.

4. Test the statement with explicit values To rule out macro issues, temporarily replace macros with hard-coded values:

   CREATE TABLE test_table (id UInt64)
   ENGINE = ReplicatedMergeTree('/clickhouse/tables/01/test_table', 'replica1')
   ORDER BY id;
   

   If this succeeds, the problem lies with macro resolution.

5. Restart ClickHouse after config changes Macro definitions are read at server startup. After editing macros, restart the service:

   sudo systemctl restart clickhouse-server
   

Best Practices

• Always define {shard} and {replica} macros in every ClickHouse server's configuration to simplify DDL and avoid human error.
• Use the default_replica_path and default_replica_name server settings to reduce boilerplate in table definitions.
• Validate DDL scripts in a staging environment before running them in production.
• Store table definitions in version control so that reviewers can catch missing parameters early.
• Use infrastructure-as-code tools to template macros from hostnames or environment variables automatically.

Frequently Asked Questions

Q: Can I create a ReplicatedMergeTree table without any arguments?
A: Yes, starting from ClickHouse 22.3 you can omit both arguments if default_replica_path and default_replica_name are set in the server configuration.

Q: What happens if two replicas share the same name?
A: You will encounter a different error -- REPLICA_ALREADY_EXISTS. Each replica in a replicated table must have a unique name.

Q: Do I need to restart ClickHouse after adding macros?
A: Yes. Macros are loaded at server startup, so a restart (or at minimum a config reload) is required for changes to take effect.

Q: Is the replica name the same as the hostname?
A: Not necessarily, but using the hostname or a derivative is a common and recommended practice since it naturally provides uniqueness across nodes.