> ## Documentation Index
> Fetch the complete documentation index at: https://docs.helix-db.com/llms.txt
> Use this file to discover all available pages before exploring further.

# helix doctor

> Check an instance's setup: runtime, storage, disk cache, memory, and index use

<div className="flex flex-wrap gap-2"><Badge color="gray" size="sm">Reference</Badge></div>

Check how an instance is set up and what to change. Doctor checks what the CLI can see itself,
then asks the server for its own checks: whether data is durable, whether the S3 bucket is in the
server's region, whether the disk cache is on local NVMe rather than network block storage like
EBS, whether caches fit in memory, and whether recent queries used indexes. Local, self-hosted,
and Cloud.

Doctor is read-only. It never changes the instance, its data, its caches, or `helix.toml`, and it
never starts a container.

## Usage

```bash theme={"languages":{"custom":["languages/helixql.json"]}}
helix doctor [INSTANCE]
helix doctor --url <URL>
```

## Arguments

| Argument | Description |
| - | - |
| `INSTANCE` | Instance or typed database (`cluster:<id>`, `tenant:<id>`). Defaults to `dev`, else the only instance, else a prompt. |

## Options

| Flag | Description | Default |
| - | - | - |
| `--url <URL>` | Diagnose the server at this base URL instead, e.g. a self-hosted server. No `helix.toml` is needed. Cannot be combined with `INSTANCE`. | — |
| `--json` | Print the report as JSON on stdout. | Off |
| `-v`, `--verbose` | Also print the details of passing checks. | Off |
| `--quiet` | Print only warnings, failures, and the summary. | Off |

## Checks

Each check passes, warns, fails, or is skipped with its reason. A warning means the setup works
but costs performance or money; a failure means it risks losing data or cannot work. Warnings and
failures print a fix.

| Check | What it looks at |
| - | - |
| `cli.version` | Whether a newer CLI is released. |
| `runtime.daemon`, `runtime.container`, `runtime.image` | Local instances: Docker or Podman answers, the container is running, and its image is not older than the one this CLI ships with. |
| `server.reachable` | The server answers `GET /healthz`. |
| `storage.durability` | Data is in S3 or on disk, not in memory only. |
| `storage.data_device` | `HELIX_DATA_DIR` is on persistent storage: not tmpfs, the container's writable layer, or ephemeral instance storage. |
| `storage.s3_region` | The S3 bucket is in the server's AWS region. The server's region comes from EC2 or ECS metadata; in a container on EC2 that needs an IMDSv2 hop limit of 2. |
| `storage.s3_latency` | The median of five S3 round trips from the server is under 50 ms. |
| `cache.device` | The disk cache is on a local SSD or NVMe instance storage, not network block storage (EBS, Persistent Disk), a network filesystem, tmpfs, or the container's writable layer. |
| `cache.space` | `HELIX_DISK_CACHE_BYTES` fits the cache's filesystem. |
| `cache.warm` | S3 storage warms the disk cache after a restart. |
| `resources.memory` | Cache budgets take at most 70% of the memory the server may use. |
| `indexes.publication` | Vector and text index publication is caught up and holds back no entries. |
| `queries.missing_indexes` | Recent queries filtered without the secondary index the planner recommends. The fix is the `helix query` command that creates each index. |
| `queries.unbounded_scans` | Recent queries read every element of a label that no index would bound. |

The query checks cover queries from the last 24 hours since the server started. A missing index
stops being reported once the index is active. Queries that only count matches are not analyzed
yet. Server checks need a server image with
`GET /v2/diagnostics`; an older server reports `server.diagnostics` as skipped. Helix Cloud manages
storage, caching, and regions, so a Cloud database reports `cloud.managed` as skipped.

## Behavior

* Prints `Helix doctor`, the target, and the server's uptime, then the checks grouped by area, and a
  summary such as `Setup works, with room to improve · 2 warnings · 9 passed`.
* Passing checks print one line; others also print their detail and fix.
* Exits `1` when any check fails, after printing the report. Warnings alone exit `0`.
* A local instance whose container is not running reports that, and skips the server checks.
* `--json` prints an object with `target`, `uptime_secs` (when the server reported its checks),
  `checks`, and `summary`. Each check has `id`, `category`, `status` (`pass`, `warn`, `fail`, or
  `skip`), `summary`, and, when present, `detail` and `fix`. The server's own report is
  [`GET /v2/diagnostics`](/database/helix-db/query-guides/http-api).

## Examples

```bash theme={"languages":{"custom":["languages/helixql.json"]}}
# Check the default instance
helix doctor

# Check a self-hosted server
helix doctor --url http://10.0.1.5:8080

# Machine-readable report for an agent or CI
helix doctor --json
```

## Related

* [`helix status`](/cli/command-reference/status) — show instance state.
* [`helix logs`](/cli/command-reference/logs) — view server logs.
* [Secondary indexes](/database/helix-db/query-guides/secondary-indexes) — create the indexes doctor recommends.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.