ClickHouse DB::Exception: Feature is not enabled at build time

The "DB::Exception: Feature is not enabled at build time" error means the ClickHouse binary you are running was compiled without support for a particular feature you are trying to use. ClickHouse is a modular system, and some capabilities — such as specific compression codecs, integrations, or authentication methods — can be excluded at compile time. The error code is FEATURE_IS_NOT_ENABLED_AT_BUILD_TIME.

Impact

The requested operation is completely unavailable and cannot be enabled through configuration or settings changes. You must switch to a ClickHouse build that includes the feature, or find an alternative approach that does not require it.

Common Causes

Using a minimal or custom ClickHouse build that was compiled with certain CMake flags disabled (e.g., -DENABLE_HDFS=OFF, -DENABLE_S3=OFF).
Running a ClickHouse package from a distribution repository that strips optional dependencies for smaller binary size.
Attempting to use Kerberos, LDAP, or other authentication backends in a build that excluded those libraries.
Trying to use a compression codec (like ZSTD, LZ4, or specific encryption codecs) that was not linked during compilation.
Running ClickHouse in a Docker image variant that omits certain features for reduced image size.

Troubleshooting and Resolution Steps

Identify the missing feature: The error message specifies which feature is unavailable. Note the exact feature name.
Check your ClickHouse build flags:
```
SELECT * FROM system.build_options WHERE name LIKE '%ENABLE%';
```
This shows which features were enabled or disabled at compile time.
Switch to the official ClickHouse build: The official packages from ClickHouse Inc. include all standard features. Install from the official repository:
```
# Debian/Ubuntu
sudo apt-get install clickhouse-server clickhouse-client

# Or use the official Docker image
docker pull clickhouse/clickhouse-server
```
Build from source with the feature enabled: If you maintain a custom build, enable the required feature in your CMake configuration:
```
cmake -DENABLE_HDFS=ON -DENABLE_S3=ON ..
make -j$(nproc)
```
Verify after installation: After switching builds, confirm the feature is available:
```
SELECT * FROM system.build_options WHERE name = 'ENABLE_S3';
```

Best Practices

Use official ClickHouse packages for production deployments unless you have a specific reason to use custom builds.
Document your custom build flags so the team knows which features are included or excluded.
When using third-party Docker images or packages, verify they include the features your workload requires before deploying.
Check build options as part of your provisioning automation to catch mismatches early.

Frequently Asked Questions

Q: Can I enable the feature without recompiling ClickHouse?
A: No. Build-time features are baked into the binary. You need a different binary that was compiled with the feature enabled.

Q: How do I know which features the official ClickHouse build includes?
A: The official build includes virtually all features. You can verify by running SELECT * FROM system.build_options on an official installation.

Q: Does this error appear in ClickHouse Cloud?
A: Generally no, because ClickHouse Cloud uses fully-featured builds. If you encounter it, contact support as it may indicate a service configuration issue.