obsessiondb · alvarogar4 · Jun 11, 2026 · Jun 10, 2026
diff --git a/apps/docs/src/content/docs/getting-started/index.mdx b/apps/docs/src/content/docs/getting-started/index.mdx
@@ -28,7 +28,7 @@ chkit is a ClickHouse schema and migration toolkit for TypeScript projects. Pick
 Both paths need the same baseline:
 
 - Node.js 20+ or Bun 1.3.5+
-- A ClickHouse endpoint (`CLICKHOUSE_URL`, optionally `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`)
+- A ClickHouse endpoint (`CLICKHOUSE_URL`, optionally `CLICKHOUSE_USER`, `CLICKHOUSE_PASSWORD`) — ClickHouse 24.x or newer (see [compatibility](/guides/clickhouse-compatibility/))
 
 ## Where to next
 
@@ -37,3 +37,4 @@ Once either path is working:
 - [CLI reference](/cli/overview/) — every command, flag, and expected output
 - [Configuration](/configuration/overview/) — wire up `clickhouse.config.ts`
 - [Schema DSL](/schema/dsl-reference/) — define tables, views, and materialized views
+- [Troubleshooting](/guides/troubleshooting/) — fixes for common errors if a command fails
diff --git a/apps/docs/src/content/docs/guides/clickhouse-compatibility.md b/apps/docs/src/content/docs/guides/clickhouse-compatibility.md
@@ -0,0 +1,30 @@
+---
+title: ClickHouse compatibility
+description: Which ClickHouse versions and engines chkit supports, and which features are version-gated.
+---
+
+chkit is developed and tested against [ObsessionDB](/obsessiondb/overview/) (a managed ClickHouse running the `SharedMergeTree` engine) and recent open-source ClickHouse releases.
+
+## Supported versions
+
+chkit targets **ClickHouse 24.x and newer**. It uses standard SQL DDL and the HTTP interface, so it works against any reasonably recent ClickHouse — self-hosted, ClickHouse Cloud, or ObsessionDB. Older versions are not tested and may reject some generated DDL.
+
+The continuous test suite runs against ObsessionDB, so the `SharedMergeTree`/`Shared*` engine families and ObsessionDB-specific DDL are the most heavily exercised paths. Vanilla single-node ClickHouse is supported for standard `MergeTree`-family engines.
+
+## Version-gated features
+
+A few schema features depend on the ClickHouse version of your target:
+
+| Feature | Requirement |
+|---------|-------------|
+| [Refreshable materialized views](/schema/refreshable-views/) | Production-ready on **24.10+** (no flag). Experimental and flag-gated on 23.12–24.9. chkit targets 24.10+. |
+| `set` data-skipping index | **ClickHouse 26+** requires the `set(0)` form rather than a bare `set`; chkit emits `set(maxRows)` accordingly. See the [DSL reference](/schema/dsl-reference/). |
+| `uniqueKey` | Renders `UNIQUE KEY` DDL, which is supported on ObsessionDB / ClickHouse Cloud engines but rejected by vanilla `MergeTree`. |
+
+If you target a single-node open-source ClickHouse, prefer the standard `MergeTree` engine family and avoid the Cloud/Shared-only features above.
+
+## Related pages
+
+- [Configuration overview](/configuration/overview/) — connection and engine settings
+- [Refreshable materialized views](/schema/refreshable-views/) — version requirements in detail
+- [Troubleshooting](/guides/troubleshooting/) — common errors and fixes
diff --git a/apps/docs/src/content/docs/guides/troubleshooting.md b/apps/docs/src/content/docs/guides/troubleshooting.md
@@ -0,0 +1,83 @@
+---
+title: Troubleshooting
+description: Common chkit errors mapped to their causes and fixes — missing dependencies, connection and auth failures, rejected migrations, blocked destructive operations, and drift.
+---
+
+A reference for the errors you are most likely to hit when running chkit, what causes each, and how to fix it. Errors are grouped by the stage where they surface: loading the project, connecting to ClickHouse, and running migrations.
+
+## Quick reference
+
+| Error message contains | Cause | Fix |
+|------------------------|-------|-----|
+| `could not load its dependencies: cannot find "@chkit/core"` | Dependencies not installed yet | Run `bun install` (or `npm`/`pnpm install`) in the project |
+| `Unknown file extension ".ts"` | Old chkit that could not load `.ts` configs under Node | Upgrade chkit — recent versions bundle a TypeScript loader |
+| `Authentication failed for user "..."` | Wrong `CLICKHOUSE_USER` / `CLICKHOUSE_PASSWORD` | Check the credentials in your environment |
+| `Could not connect to ClickHouse at ... (connection refused)` | Nothing listening at the URL | Confirm the server is running and `CLICKHOUSE_URL` host/port are correct |
+| `Could not connect to ClickHouse at ... (host not found)` | Typo'd or unresolvable host | Check the host in `CLICKHOUSE_URL` |
+| `Unknown data type family: ...` | A migration references an invalid ClickHouse type | Fix the column type in the schema/migration and regenerate |
+| `Blocked destructive migration execution` (exit code 3) | A `risk=danger` operation in non-interactive mode | Review, then re-run with `--allow-destructive` |
+| `Checksum mismatch detected on applied migrations` (exit code 1) | A migration file was edited after being applied | Restore the original file, or apply a new forward migration |
+| `extra_object` entries in `drift` / `check` | Tables chkit does not manage exist in the database | Expected on shared databases; only fails CI if you opt into `check.failOnExtraObjects` |
+
+## Project loading
+
+### `could not load its dependencies: cannot find "@chkit/core"`
+
+The config (`clickhouse.config.ts`) and your schema files import `@chkit/core`, but it is not installed yet. This commonly happens when you run a command immediately after `chkit init`, before installing.
+
+Install the dependencies in the project directory:
+
+```sh
+bun add -d chkit @chkit/core
+```
+
+### `Unknown file extension ".ts"`
+
+Older chkit versions could not load a TypeScript config under plain Node. Recent versions bundle a loader, so the fix is to upgrade:
+
+```sh
+bun add -d chkit@latest
+```
+
+Under Bun this never occurred; under Node it now works the same way.
+
+## Connecting to ClickHouse
+
+### `Authentication failed for user "<user>" at <url>`
+
+`CLICKHOUSE_USER` or `CLICKHOUSE_PASSWORD` is wrong. chkit collapses the raw ClickHouse auth blurb (Cloud reset URLs, server file paths) into this single line. Verify the credentials your environment exports.
+
+### `Could not connect to ClickHouse at <url> (<reason>)`
+
+The endpoint is unreachable. The reason narrows it down:
+
+- **connection refused** — nothing is listening on that host/port. Confirm the server is up and the port is right.
+- **host not found** — the host does not resolve. Check for a typo in `CLICKHOUSE_URL`.
+- **connection timed out** / **host unreachable** — a network or firewall issue between you and the server.
+
+If `CLICKHOUSE_URL` is unset, chkit falls back to `http://localhost:8123`; the message says so when that is what happened.
+
+## Running migrations
+
+### `Unknown data type family: <type>`
+
+ClickHouse rejected a statement because a column type is not valid (for example a typo like `NotARealType`). Fix the type in the schema definition, regenerate the migration, and re-apply.
+
+### `Blocked destructive migration execution` (exit code 3)
+
+A migration contains a destructive operation (`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DETACH`, …) and you are running non-interactively without approval. After reviewing the plan, re-run with `--allow-destructive` (or set `safety.allowDestructive: true` in config). See [`chkit migrate`](/cli/migrate/#destructive-operation-safety).
+
+### `Checksum mismatch detected on applied migrations` (exit code 1)
+
+A migration file changed on disk after it was already applied — chkit verifies SHA-256 checksums before applying. Restore the original file content, or, if the change is intentional, write a new forward migration instead of editing history.
+
+### `extra_object` reported by `drift` / `check`
+
+On a shared or pre-existing database, every table chkit does not manage is reported as an `extra_object`. By default these are informational and do **not** fail `check`. They only flip the gate to failing if you opt in with `check.failOnExtraObjects: true`. See [`chkit drift`](/cli/drift/) and [`chkit check`](/cli/check/).
+
+## Related pages
+
+- [Configuration overview](/configuration/overview/) — config fields and environment variables
+- [`chkit migrate`](/cli/migrate/) — applying migrations and destructive-operation safety
+- [`chkit status`](/cli/status/) — inspecting migration state
+- [CI/CD Integration](/guides/ci-cd/) — running chkit unattended
diff --git a/packages/cli/README.md b/packages/cli/README.md
@@ -46,6 +46,11 @@ bunx chkit check
 
 All commands support `--json` for machine-readable output and `--config <path>` to specify a custom config file.
 
+## Requirements
+
+- **Node 20+** or **Bun** — chkit loads your TypeScript config and schema files on both runtimes.
+- **ClickHouse 24.x or newer** — chkit targets recent ClickHouse (self-hosted, ClickHouse Cloud, or ObsessionDB). Some schema features are version-gated; see [ClickHouse compatibility](https://chkit.obsessiondb.com/guides/clickhouse-compatibility/).
+
 ## Plugins
 
 | Plugin | Description |