ClickHouse DB::Exception: Format version too old

The "DB::Exception: Format version too old" error in ClickHouse occurs when the server encounters a data file or part that uses an internal storage format no longer supported by the running ClickHouse version. As ClickHouse evolves, older on-disk formats may be deprecated and eventually dropped. The error code is FORMAT_VERSION_TOO_OLD.

Impact

Any table or partition containing data in the outdated format becomes unreadable. Queries against affected tables will fail, and the server may refuse to start if critical system tables use the old format. This can block upgrades and data access until the issue is resolved.

Common Causes

1. Upgrading ClickHouse across multiple major versions without running intermediate upgrades that would have migrated the data format.
2. Restoring a backup made with a very old ClickHouse version into a much newer instance.
3. Manually copying data parts from an old ClickHouse installation into a new one.
4. Downgrading and then upgrading again, which can leave parts in an inconsistent format state.

Troubleshooting and Resolution Steps

1. Identify affected tables and parts: Check the ClickHouse error log for specific table and part names that triggered the error.

2. Check ClickHouse version compatibility: Consult the ClickHouse changelog to understand which format versions are supported by your current release and what migration path is recommended.

3. Perform incremental upgrades: If you skipped several major versions, install an intermediate version that supports both the old and new formats. Start the server, let it convert or merge the parts, then upgrade to the target version:

   # Example: upgrading from 20.x to 24.x
   # First upgrade to 22.x, let it run and convert data
   # Then upgrade to 24.x
   

4. Force a merge to rewrite parts: Once running a version that can read the old format, force merges to rewrite the data in the current format:

   OPTIMIZE TABLE my_table FINAL;
   

5. Re-import from backup: If intermediate upgrades are impractical, export the data from the old ClickHouse version using clickhouse-client or SELECT ... INTO OUTFILE in a portable format (CSV, Parquet), then import into the new version.

6. Check system tables: If system tables themselves have old formats, you may need to delete them and let ClickHouse recreate them on startup (back up metadata first).

Best Practices

• Follow ClickHouse's recommended upgrade path and avoid skipping more than one or two major versions at a time.
• Run OPTIMIZE TABLE ... FINAL on critical tables after each major upgrade to ensure parts are rewritten in the current format.
• Test upgrades in a staging environment with a copy of production data before applying to production.
• Maintain regular backups that can be restored on both old and new versions.

Frequently Asked Questions

Q: Can I force ClickHouse to read the old format?
A: No. Once support for a format version is removed from the source code, the binary cannot interpret it. You must use an intermediate version that supports the format.

Q: How do I know which format version my data parts use?
A: Check the format_version file inside each data part directory under /var/lib/clickhouse/data/<database>/<table>/. You can also query system.parts for version metadata.

Q: Will OPTIMIZE TABLE FINAL rewrite all parts to the latest format?
A: Yes, merging parts rewrites them using the current format version. Running OPTIMIZE TABLE ... FINAL ensures all parts are merged and updated.