ClickHouse DB::Exception: Unknown codec

The "DB::Exception: Unknown codec" error in ClickHouse occurs when a CODEC() clause references a codec name that the server does not recognize. The UNKNOWN_CODEC error is raised at DDL time -- when creating or altering a table -- if the specified codec is not among the built-in or registered codecs for that ClickHouse build. Unlike syntax errors, the codec expression is well-formed, but the name itself is not found.

Impact

The DDL statement that contains the unrecognized codec will be rejected. No table or column changes are applied. Existing tables and data remain unaffected. However, if you are trying to restore a schema from a different ClickHouse version that included a codec not present in your current build, this error can block migrations.

Common Causes

1. Typo in the codec name (e.g., CODEC(ZST) instead of CODEC(ZSTD))
2. Using a codec that was introduced in a newer version of ClickHouse than what is currently running
3. Referencing a codec that was removed or renamed in a ClickHouse upgrade
4. Attempting to use an experimental codec that requires a specific setting to be enabled
5. Importing a CREATE TABLE statement from a ClickHouse build compiled with custom codecs
6. Confusing compression method names from other systems (e.g., gzip, snappy) with ClickHouse codec names

Troubleshooting and Resolution Steps

1. Verify the codec name against the list of supported codecs. The standard codecs in ClickHouse are:

   • General-purpose: NONE, LZ4, LZ4HC, ZSTD
   • Preprocessing: Delta, DoubleDelta, Gorilla, FPC, T64

2. Check your ClickHouse version:

   SELECT version();
   

   Some codecs were added in specific versions. For instance, FPC was added in version 22.6.

3. Check for experimental codecs that may require enabling a setting:

   SET allow_experimental_codecs = 1;
   

   Some codecs like AES_128_GCM_SIV or AES_256_GCM_SIV require allow_experimental_codecs to be enabled.

4. Fix typos in your DDL. Common misspellings include:

   -- Wrong
   CODEC(ZSDT)  -- transposed letters
   CODEC(Deltta) -- extra letter
   -- Correct
   CODEC(ZSTD)
   CODEC(Delta)
   

5. If migrating schemas between versions, adapt the codec to one supported by your target version:

   -- If FPC is not available, use a different codec
   ALTER TABLE your_table MODIFY COLUMN your_column CODEC(ZSTD(1));
   

6. Review the ClickHouse documentation for codec availability per version if you are working across multiple clusters with different versions.

Best Practices

• Standardize on widely supported codecs (LZ4, ZSTD) across your fleet to avoid compatibility issues.
• When writing automation or migration scripts, include version checks before applying codec-specific DDL.
• Document which codecs are in use across your tables so that version upgrades and downgrades can be planned accordingly.
• Avoid experimental codecs in production unless you have tested them thoroughly and accept the stability trade-offs.

Frequently Asked Questions

Q: Where can I find the complete list of codecs for my ClickHouse version?
A: The official ClickHouse documentation lists all supported codecs. You can also check by attempting to create a test table with the codec. If it succeeds, the codec is supported.

Q: Can I register custom codecs in ClickHouse?
A: ClickHouse does not support user-defined compression codecs at runtime. All codecs must be compiled into the ClickHouse binary. If you need a custom codec, you would need to build ClickHouse from source with your codec included.

Q: I see UNKNOWN_CODEC when restoring a backup. What should I do?
A: This means the backup was created on a ClickHouse version with codecs not available on your current server. Either upgrade your server to match the source version, or modify the DDL in the backup to replace unsupported codecs before restoring.