Skip to main content
For the complete documentation index optimized for AI agents, see 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
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

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: 
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: 
helix query dev --file examples/request.json
See helix query for the request shape.

​
helix deploy

Use helix push <instance> to deploy an Enterprise Cloud instance.

​
--path reported as an unexpected argument

--path is only valid on helix init (it sets the project directory). 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

ErrorCauseFix
project name is empty in <path>[project] name is blank.Set a non-empty name.
<path> has no instances configuredNo [local.*] or [enterprise.*] blocks.Run helix add local or helix add cloud.
instance name is empty in <path>Empty key like [local.""].Give the instance a name.
cluster_id is empty for '<name>' in <path>Missing required Helix Cloud field.Set cluster_id under [enterprise.<name>].
Failed to parse helix.toml: invalid typeNumbers quoted as strings.Use bare numbers — port = 6969, not port = "6969".

​
Instance '<name>' not found

The instance is not listed in helix.toml. Check with helix status and add it with helix add.

​
Docker / Podman issues

​
Docker daemon not running

Docker is not available. Install/start docker and try again
A container runtime must be both installed and running — installing Docker is not enough if the daemon is stopped. helix start attempts to start it for you, but surfaces this error when it can’t.
  • 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

sudo usermod -aG docker $USER
newgrp docker

​
Port already in use

bind: address already in use

lsof -i :6969
Either stop the conflicting process or override the port for this run: 
helix start dev --port 9090
Or change [local.<instance>] port in helix.toml permanently.

​
Container name conflict

The CLI names containers helix-<project>-<instance>. If a stale container exists, remove it: 
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 <instance> --follow to investigate.

​
Authentication issues

​
Authentication required

Authentication required. Run 'helix auth login' first.
Run helix auth login. Credentials are stored in ~/.helix/credentials.

​
Stale credentials

helix auth logout
helix auth login

​
Helix Cloud query issues

​
gateway_url is not configured

Enterprise gateway URL is not configured for '<instance>'.
Run 'helix sync <instance>' or set gateway_url in helix.toml.
Run helix sync <instance> 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.<instance>] once you know it.

​
Environment variable HELIX_API_KEY is required

The auth env var named by query_auth_env is unset. 
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 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 <instance> --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 <rfc3339> --end <rfc3339> instead.

​
Destructive command issues

​
Refusing to delete '<instance>' non-interactively

helix delete <instance> --yes

​
Refusing to prune all instances non-interactively

helix prune --all --yes
helix 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 and helix prune --all.
  • 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 <instance> --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

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)