> ## 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. # Troubleshooting > Solutions to common issues and error messages in Helix CLI v2 > For the complete documentation index optimized for AI agents, see [llms.txt](/llms.txt). This guide helps you resolve common issues with the Helix CLI v2. ## Installation issues ### `command not found: helix` The CLI installs to `~/.helix/bin/helix`. If your shell can't find it after running the installer: ```bash theme={"languages":{"custom":["languages/helixql.json"]}} # Bash echo 'export PATH="$HOME/.helix/bin:$PATH"' >> ~/.bashrc source ~/.bashrc # Zsh echo 'export PATH="$HOME/.helix/bin:$PATH"' >> ~/.zshrc source ~/.zshrc ``` Verify the binary exists with `ls -la ~/.helix/bin/helix`. ### Updating the CLI ```bash theme={"languages":{"custom":["languages/helixql.json"]}} helix update # update to the latest release helix update --force # reinstall even if already on the latest version helix update --v1 # update to v2.3.5 for v1 projects ``` ### Update check fails or hangs on a restricted network On its first run, the CLI checks `https://api.github.com` (once, then cached for 24h) for a newer release. This never fails a command — network errors are ignored — but in sandboxes, CI, or rate-limited/offline environments the check can add a few seconds of latency. Skip it entirely with: ```bash theme={"languages":{"custom":["languages/helixql.json"]}} export HELIX_NO_UPDATE_CHECK=1 # also accepts HELIX_DISABLE_UPDATE_CHECK ``` ## Unrecognized commands ### `helix compile` / `helix check` These commands do **not** exist in HelixDB v2. There is no client-side compile or validation step — queries are validated **server-side** when you send them to a running instance. Author a JSON dynamic query and run it: ```bash theme={"languages":{"custom":["languages/helixql.json"]}} helix query dev --file examples/request.json ``` See [`helix query`](/cli/command-reference/query) for the request shape. ### `helix deploy` Use [`helix push `](/cli/command-reference/push) to deploy an Enterprise Cloud instance. ### `--path` reported as an unexpected argument `--path` is valid on [`helix init`](/cli/command-reference/init) and [`helix add`](/cli/command-reference/add), in either position (`helix init --path ./app local` or `helix init local --path ./app`). Older CLI versions only accepted `--path` *before* the subcommand — if you hit this error there, run [`helix update`](/cli/command-reference/update) or move the flag. Other commands locate the project by walking up from the current directory to find `helix.toml`; `cd` into the project instead. ## Project configuration issues ### `Not in a Helix project directory` ``` Not in a Helix project directory. Run 'helix init' to create one. ``` Either run `helix init` to scaffold a new project, or `cd` into a directory that contains `helix.toml`. ### `helix.toml` validation errors | Error | Cause | Fix | | -------------------------------------------- | ------------------------------------------ | ------------------------------------------------------------------------- | | `project name is empty in ` | `[project] name` is blank. | Set a non-empty `name`. | | ` has no instances configured` | No `[local.*]` or `[enterprise.*]` blocks. | Run [`helix add local`](/cli/command-reference/add) or `helix add cloud`. | | `instance name is empty in ` | Empty key like `[local.""]`. | Give the instance a name. | | `cluster_id is empty for '' in ` | Missing required Helix Cloud field. | Set `cluster_id` under `[enterprise.]`. | | `Failed to parse helix.toml: invalid type` | Numbers quoted as strings. | Use bare numbers — `port = 6969`, not `port = "6969"`. | ### `Instance '' not found` The instance is not listed in `helix.toml`. Check with `helix status` and add it with [`helix add`](/cli/command-reference/add). ## Docker / Podman issues ### Docker not installed or daemon not running ``` Docker is not installed (`docker` not found on PATH) Docker is not running ``` (Older CLI versions print `Docker is not available. Install/start docker and try again` for both cases.) A container runtime must be both **installed and running** — installing Docker is not enough if the daemon is stopped. `helix start` attempts to start an installed-but-stopped daemon for you, and surfaces these errors when it can't. If Docker is missing but Podman is installed, the CLI suggests switching: set `[project] container_runtime = "podman"` in `helix.toml`. To install a runtime: macOS — `brew install --cask docker` (Docker Desktop) or `brew install colima docker && colima start`; Linux — `curl -fsSL https://get.docker.com | sh`, or `apt-get install -y podman`. To start an installed runtime: * **macOS:** `open -a Docker`, or `colima start` / `podman machine start`. * **Linux:** `sudo systemctl start docker`. * **Headless / sandbox (no init system):** start the daemon directly, e.g. `sudo dockerd > /tmp/dockerd.log 2>&1 &`, then verify with `docker info`. Many sandboxes ship the Docker binary but do not start `dockerd` for you. * **Podman:** ensure `podman` is on `PATH` and set `[project] container_runtime = "podman"` in `helix.toml`. **Rootless Podman** needs `newuidmap`/`subuid`/`subgid` set up and frequently fails in restricted or rootless containers (namespace/mount errors) — install Docker or use a privileged container there instead. ### Permission denied on Docker socket ``` permission denied while trying to connect to the Docker daemon socket ``` ```bash theme={"languages":{"custom":["languages/helixql.json"]}} sudo usermod -aG docker $USER newgrp docker ``` ### Port already in use ``` bind: address already in use ``` ```bash theme={"languages":{"custom":["languages/helixql.json"]}} lsof -i :6969 ``` Either stop the conflicting process or override the port for this run: ```bash theme={"languages":{"custom":["languages/helixql.json"]}} helix start dev --port 9090 ``` Or change `[local.] port` in `helix.toml` permanently. ### Container name conflict The CLI names containers `helix--`. If a stale container exists, remove it: ```bash theme={"languages":{"custom":["languages/helixql.json"]}} docker rm -f helix-my-helix-app-dev ``` `helix start` removes prior containers with the same name automatically, but a foreign container outside the CLI's control may need manual cleanup. ### Local runtime did not become ready in time ``` local Helix did not become ready in time hint: check logs with 'helix logs' or verify port 6969 is reachable ``` The `enterprise-dev` container started but did not accept `POST /v1/query` within \~30 seconds. Tail the container with `helix logs --follow` to investigate. ## Authentication issues ### `Authentication required` ``` Authentication required. Run 'helix auth login' first. ``` Run [`helix auth login`](/cli/command-reference/auth). Credentials are stored in `~/.helix/credentials`. ### Stale credentials ```bash theme={"languages":{"custom":["languages/helixql.json"]}} helix auth logout helix auth login ``` ## Helix Cloud query issues ### `gateway_url is not configured` ``` Enterprise gateway URL is not configured for ''. Run 'helix sync ' or set gateway_url in helix.toml. ``` Run [`helix sync `](/cli/command-reference/sync) to fetch the latest metadata. If `helix sync` reports `gateway_url is still missing`, the cluster's gateway hasn't been published yet — set `gateway_url` manually under `[enterprise.]` once you know it. ### `Environment variable HELIX_API_KEY is required` The auth env var named by `query_auth_env` is unset. ```bash theme={"languages":{"custom":["languages/helixql.json"]}} export HELIX_API_KEY="..." ``` ### `--warm is only valid for read requests` `helix query --warm` is rejected for write requests. Remove `--warm` or change `request_type` to `"read"`. ### `request_type must be lowercase 'read' or 'write'` `request_type` must be either `"read"` or `"write"`. Capitalized or alternative values are rejected. ### `dynamic query request must include query` The JSON file is missing the top-level `query` object. See [`helix query`](/cli/command-reference/query) for the request shape. ## Logs issues ### `--range, --start, and --end are only supported for Enterprise logs` Range queries are Helix Cloud-only. For local instances, use `helix logs --follow` to tail the container. ### `live Enterprise logs are not supported yet` `helix logs --follow` on a Helix Cloud instance is rejected. Use `--range --start --end ` instead. ## Destructive command issues ### `Refusing to delete '' non-interactively` ```bash theme={"languages":{"custom":["languages/helixql.json"]}} helix delete --yes ``` ### `Refusing to prune all instances non-interactively` ```bash theme={"languages":{"custom":["languages/helixql.json"]}} helix prune --all --yes ``` [`helix prune`](/cli/command-reference/prune) only removes Helix-owned containers, networks, disk-mode volumes, and per-instance workspace directories — it never runs a broad `docker/podman system prune`. ## Interactive vs scripted use The CLI uses `cliclack` prompts when stdin is a TTY and a required choice is missing — for example, `helix init` with no subcommand, or `helix start` when multiple local instances exist and no instance is passed. In non-interactive contexts (CI, pipes, scripts): * Pass subcommands and required flags explicitly. * Use `--yes` for [`helix delete`](/cli/command-reference/delete) and [`helix prune --all`](/cli/command-reference/prune). * The CLI fails clearly when a required choice cannot be resolved — it never silently picks a default. ## Quick checks before reporting an issue * [ ] Update the CLI: `helix update` * [ ] Check instances and runtime state: `helix status` * [ ] Tail container logs: `helix logs --follow` * [ ] Restart Docker / Podman * [ ] Clean up Helix-owned resources: `helix prune` * [ ] Check disk space: `df -h` * [ ] Confirm `helix.toml` parses: re-run the failing command — config errors print the offending path ## Getting help * Documentation: [docs.helix-db.com](https://docs.helix-db.com) * GitHub issues: [github.com/HelixDB/helix-db/issues](https://github.com/HelixDB/helix-db/issues) * Discord: [discord.gg/2stgMPr5BD](https://discord.gg/2stgMPr5BD) * Email: [founders@helix-db.com](mailto:founders@helix-db.com) When reporting an issue, include: * `helix --version` * Operating system + container runtime version * The exact command and full error output * A scrubbed `helix.toml` (remove cluster IDs, gateway URLs, auth env names if sensitive)