ClickHouse DB::Exception: Cannot load configuration file

The CANNOT_LOAD_CONFIG error means ClickHouse is unable to read or parse one of its configuration files. You will typically see DB::Exception: Cannot load configuration file '/etc/clickhouse-server/config.xml' (or whichever file is at fault). This error most often prevents the server from starting at all, making it one of the more disruptive errors you can encounter.

Impact

When this error occurs at startup, ClickHouse will not start. If it happens during a live config reload (triggered by SYSTEM RELOAD CONFIG or a file-watcher event), the server will continue running with its previous configuration but will log the error and refuse to apply the new settings. Either way, any intended configuration changes will not take effect until the underlying problem is fixed.

Common Causes

Malformed XML -- Missing closing tags, unescaped special characters (&, <, >), or invalid XML structure.
Malformed YAML -- Incorrect indentation, tabs instead of spaces, or invalid YAML syntax (for ClickHouse versions supporting YAML configs).
File permission issues -- The clickhouse system user cannot read the config file or one of its included fragments.
Missing included files -- The main config uses <include_from> or incl attributes pointing to files that do not exist.
Encoding issues -- Config file saved with BOM (Byte Order Mark) or in a non-UTF-8 encoding.
Disk or filesystem problems -- The config file is on a volume that is not mounted or is corrupted.

Troubleshooting and Resolution Steps

Validate the XML syntax: Use xmllint or a similar tool to check for structural errors:
```
xmllint --noout /etc/clickhouse-server/config.xml
```
This will report the line and column of any XML parsing error.
Check file permissions:
```
ls -la /etc/clickhouse-server/config.xml
ls -la /etc/clickhouse-server/config.d/
```
The files must be readable by the clickhouse user (or the user running the ClickHouse process). Typical permissions are 644 with ownership by root or clickhouse.
Verify included files exist: Search for incl attributes and <include_from> directives:
```
grep -r 'incl=' /etc/clickhouse-server/config.xml
grep -r 'include_from' /etc/clickhouse-server/config.xml
```
Ensure every referenced file is present and readable.
Check config.d directory fragments: ClickHouse loads all .xml (and .yaml/.yml) files from config.d/ and users.d/ directories. A broken fragment in any of these files can cause the error:
```
for f in /etc/clickhouse-server/config.d/*.xml; do
    echo "Checking $f..."
    xmllint --noout "$f"
done
```
Look for encoding problems:
```
file /etc/clickhouse-server/config.xml
```
The output should indicate UTF-8 or ASCII. If it mentions BOM or a different encoding, convert the file:
```
iconv -f UTF-8-BOM -t UTF-8 config.xml > config_fixed.xml
```
Review the server error log: Even when the server fails to start, it usually writes a partial log:
```
tail -n 100 /var/log/clickhouse-server/clickhouse-server.err.log
```
The log typically includes the specific file path and line number where parsing failed.
Test with a minimal config: If you cannot find the issue, temporarily replace the config with a minimal valid one to confirm the server can start, then incrementally re-add sections to isolate the problem.

Best Practices

Keep configuration files under version control (Git) so you can easily diff and revert changes.
Validate XML syntax before applying changes -- add a pre-commit hook or CI step that runs xmllint.
Use the config.d/ and users.d/ override directories rather than editing the main config files directly. This makes upgrades cleaner and errors easier to isolate.
Maintain a known-good backup of your configuration files on the same server.
When using YAML configuration, ensure your editor is configured to use spaces (not tabs) for indentation.

Frequently Asked Questions

Q: Can I use YAML instead of XML for ClickHouse configuration?
A: Yes, starting from ClickHouse 22.3. You can place .yaml or .yml files in config.d/ and users.d/. However, the main config file format depends on what the startup script references. Ensure your YAML is valid -- incorrect indentation is the most common issue.

Q: ClickHouse was working and suddenly cannot load config after an OS update. What happened?
A: OS updates can change file permissions or SELinux/AppArmor policies. Check that the clickhouse user still has read access to all config files and that no security policy is blocking access.

Q: The error mentions a specific line number. How do I find it?
A: Open the file in an editor that displays line numbers and go to the indicated line. Common issues at a specific line include unclosed XML tags, stray characters, or improperly escaped ampersands (use & instead of &).

Q: Can a config reload fail without taking down the server?
A: Yes. If the server is already running and you trigger a reload (SYSTEM RELOAD CONFIG), a parsing error will cause the reload to fail, but the server continues running with its previous valid configuration. The error is logged.