ClickHouse DB::Exception: Unknown element in configuration

The UNKNOWN_ELEMENT_IN_CONFIG error is raised when ClickHouse encounters an XML or YAML tag in a configuration file that it does not recognize. A typical message looks like DB::Exception: Unknown element in config: 'maxmemoryusage', expected one of: .... This usually indicates a typo in the element name or the use of a configuration directive from a different ClickHouse version.

Impact

ClickHouse may refuse to start if the unknown element is in a critical configuration section, or it may log a warning and skip the element depending on the context. In either case, the intended configuration will not be applied. If the unknown element was supposed to define an important setting like memory limits or storage policies, running without it could lead to unexpected resource consumption or behavior.

Common Causes

Typo in the element name -- Writing <max_memory_ussage> instead of <max_memory_usage>, or using camelCase instead of snake_case.
Element from a different ClickHouse version -- A config directive that was added in a newer version or removed in the current one.
Wrong section placement -- Putting an element in the wrong part of the config hierarchy (e.g., a server-level setting inside <profiles>).
Copy-paste from third-party documentation -- Configuration examples from blogs or forums may contain non-standard or deprecated elements.
Custom config fragments with errors -- Files in config.d/ or users.d/ that contain misspelled element names.

Troubleshooting and Resolution Steps

Read the error message carefully: The error typically states the unrecognized element name and sometimes lists expected alternatives. Use this to identify the typo or incorrect element.
Check spelling against the documentation: ClickHouse configuration elements use snake_case. Verify the exact element name in the official documentation for your version.
Search for the element across all config files:
```
grep -rn 'maxmemoryusage\|unknown_element_name' /etc/clickhouse-server/
```
This helps locate the offending file, especially when using multiple config fragments.
Verify the element belongs in the correct section: ClickHouse config has a specific hierarchy. For example, <max_memory_usage> belongs under a profile in <profiles>, not at the top level of config.xml. Consult the documentation for proper placement.
Check your ClickHouse version:
```
SELECT version();
```
Some elements were introduced in specific versions. For example, <named_collections> was added in ClickHouse 22.4. Using it on an older version will produce this error.
Remove or comment out the unknown element: If the element is not needed or was added by mistake, comment it out:
```

```
Then reload the configuration:
```
SYSTEM RELOAD CONFIG;
```
Validate configuration before restarting: Some ClickHouse versions support a config check mode:
```
clickhouse-server --config-file=/etc/clickhouse-server/config.xml --check-config
```

Best Practices

Use config.d/ override files rather than modifying the main config.xml, so you can easily identify and remove problematic additions.
Validate all configuration changes against the documentation for your specific ClickHouse version before applying them.
Keep a changelog of configuration modifications so you can trace when and why elements were added.
When upgrading ClickHouse, review the changelog for any configuration changes and update your files accordingly.
Use an XML editor or linter that can flag unknown elements against a schema (though ClickHouse does not provide a formal XSD).

Frequently Asked Questions

Q: Will ClickHouse always refuse to start with an unknown element?
A: Not always. Some sections of the config are more strict than others. In many cases, ClickHouse will log a warning and continue. However, elements in critical sections like storage configuration or cluster definitions may cause a startup failure.

Q: How can I tell which config file contains the unknown element?
A: Check the server error log -- it usually includes the file path and line number. You can also search all config files with grep -rn 'element_name' /etc/clickhouse-server/.

Q: I added a custom element for my own use. Can I make ClickHouse ignore it?
A: ClickHouse does not support arbitrary custom elements in its config files. If you need to store custom metadata alongside the config, use a separate file that your tooling reads independently.

Q: Does this error apply to YAML config files too?
A: Yes. Whether you use XML or YAML configuration, ClickHouse validates the element (key) names. An unrecognized key in a YAML config file will produce the same UNKNOWN_ELEMENT_IN_CONFIG error.