Troubleshooting Altinity Stable® Builds

Figuring out what’s wrong when something goes wrong

The ClickHouse® development process moves quickly. Thanks to the hard work of the ClickHouse community, the product’s thousands of core features are all well-tested and stable. To maintain that stability, ClickHouse is built with a CI system that runs tens of thousands of tests against every commit.

But as with any other software, bad things may happen.

Most bugs occur in new functionality or in a set of features that may not have been fully tested together. (Sadly, combinatorics make that last part impossible.) However, new features tend to be adopted by the ClickHouse community quickly, fleshing out any bugs that might have been missed in testing.

What should I do if I found a bug in ClickHouse?

  1. First of all, if you’re an Altinity customer, you can contact Altinity support to file an issue. (If you’d like to go through the troubleshooting tips outlined here before you reach out to us, that’s fine but not necessary.)
  2. If you’re not an Altinity customer, try to upgrade to the latest bugfix release. If you’re using v21.3.5.42-lts but you know that v21.3.10.1-lts exists, start by upgrading to the bugfix. Upgrades to the latest maintenance releases are smooth and safe.
  3. Look for similar issues in the ClickHouse/ClickHouse or Altinity/ClickHouse repos; hopefully the problem has been logged and a fix is on the way.
  4. If you can reproduce the bug, try to isolate it. For example, remove pieces of a failing query one by one, creating the simplest scenario where the error still occurs. Creating a minimal reproducible example is a huge step towards a solution.
  5. Once you have that minimal reproducible example, see if it fails on the newest version of ClickHouse (not just the latest bugfix release of the version you’re using).