Troubleshooting

This page is the index: find what you saw, and it sends you to the page that owns the fix. Every command, concept, and integration page carries its own If … fails section with verbatim error strings; this page exists for when you do not yet know which one owns your problem.

Below the index are the diagnostics that genuinely span commands — integrity, environment recreation, and the outbound MCP server — which live here because no single page owns them.

Prerequisites

Collect the exact command, installed version, exit code, and safe JSON error before anything else:

hlix --version
hlix <command> --json
echo $?

Expected result: a versioned envelope whose error.code is the value to search for below.

{"schemaVersion":1,"command":"push","error":{"code":"conflict","message":"…","status":409}}

Do not paste API keys, protected-file values, raw dotenv contents, or full credential files into support requests.

By error code

Branch on error.code, never on error.message. Every code the CLI can emit is defined in the CLI reference; this maps each to the page that explains what to do.

Code	Usually means	Fix lives at
unauthenticated	No credential, or the key was rejected	hlix auth
forbidden	Valid key, wrong workspace or role	hlix auth
missing_credential	No key entered at the prompt	hlix auth
invalid_base_url	--base-url is not HTTPS or loopback	hlix auth
workspace_mismatch	An override contradicts the folder’s binding	CLI reference
workspace_required	Nothing in the chain named a workspace	hlix import
not_initialized	The folder is not bound to a project	hlix push, pull & sync
already_imported	The folder is bound; push instead	hlix import
scan_blocked	The import scan found a blocker	Import a project
conflict	Both sides moved, or a compare-and-swap lost	hlix push, pull & sync
approval_required	The caller could not be asked	hlix push, pull & sync
cancelled	An interactive prompt was declined	hlix push, pull & sync
not_found	No such resource in this workspace	hlix projects
missing_argument	A required positional was omitted	CLI reference
invalid_usage	Unknown flag, bad value, or too many arguments	CLI reference
unknown_command	No such command	CLI reference
unreachable	The API could not be contacted	hlix status
rate_limited · server_error · not_implemented	The API refused or failed	API reference

`approval_required` and `cancelled` are the two halves of one gate

The first means “you could not be asked here” — a --json or non-interactive caller was refused rather than defaulted to yes. The second means “you answered no”. Neither changed anything. Review with --dry-run, then repeat with --yes.

By what you saw

Symptom	Fix lives at
hlix: command not found, or npm E404	Install the CLI
An install command that fails	Current versions
The dry run reports blockers	Move an existing project
A detected environment plan looks wrong	Environment discovery
A secret is empty inside a task	Secrets & protected files
An imported skill, agent, or MCP server stayed inert	Import trust model
A resource import was refused	hlix skill, agent & mcp import
A task never starts, or names an unavailable harness	Connect your agents
A task exists but will not run	Tasks
A cycle will not execute	Cycles
Review evidence is missing or stale	Reviewing output
An approval will not resolve	Approvals
The workspace terminal will not open	The Coding Workspace
A memory never reaches a run	Context, memory & DNA
GitHub, Linear, or Telegram will not connect	Integrations
An SDK call throws	TypeScript · Python · Go
A generated client is missing an endpoint	API reference
Behaviour changed after an upgrade	Changelog

Integrity and concurrency

These refusals are deliberate and are not recoverable with --force. They exist so a revision can never contain a mixture of two states.

Source changed after the scan

A file’s size or hash moved while the snapshot was being built. Stop background generators, watchers, or editors, then rerun. hlix stops rather than uploading a mixed state.

Integrity verification failed

Retry once over a trusted connection. A repeated hash, size, Git-bundle, commit, base64, or manifest mismatch indicates corrupted or inconsistent data, not a transient fault. Do not reach for --force; it does not apply to integrity.

The project has active tasks

A running task can advance the cloud revision underneath you. Wait for a terminal status, then reconcile:

hlix tasks watch <task-id>
hlix sync

A protected path was refused

hlix will not write through a symlink or a non-directory parent, and will not replace a device or directory with protected bytes. Inspect each path with ls -ld, remove only the unsafe local entry after confirming what it is, then retry.

Environment recreation

The scan produces a plan; these are the three ways the plan and reality disagree.

Confidence is low

Add an explicit source — .cursor/environment.json or a Dev Container file — pin tool versions, and commit the package-manager lockfile. Explicit configuration outranks every inference. Re-run hlix import --dry-run and read the plan.

A setup command fails in the cloud

Run the same command locally in a clean environment and review dependency lifecycle scripts. Check whether the required key names appear in the dry-run report: a missing protected secret stops dispatch outright, while a variable only the application needs may fail later, inside its own setup command.

It works locally and not in the cloud

Compare runtime versions, architecture-specific dependencies, implicitly-installed global tools, ignored files, ports, and credentials. Make those assumptions declarative in the repository rather than patching the Coding Workspace by hand — a hand-patched sandbox is not reproducible and does not survive a recreate.

The official MCP server

This is the outbound @hlix/mcp server that local agent clients run. It is a different thing from importing a third-party MCP definition into a cloud project (that is here).

The package or Registry entry is missing

Use the exact version shown on the MCP server page. A client that cannot resolve it is usually pinned to a version that was never published — check the pin against Current versions.

The server exits before initialization

Confirm node --version is 22.13 or later. Then confirm the client launches npx directly, with the pinned package as a separate argument — not wrapped in a shell string.

Tools point at the wrong project

Start the client from the initialized project root, or pass an explicit project ID. The server reads .hlix/config.json from its working directory and deliberately does not search parent or home directories.

Write tools are absent

That is the secure default. Set HLIX_MCP_ALLOW_WRITES=1 in the server process environment and restart the client. The tool list should then add exactly three: task creation, task comments, and cycle proposals.

The client shows malformed protocol output

The server reserves stdout for MCP messages. Capture stderr only, redact local paths and IDs as your policy requires, and include the package version plus the client’s initialization error.

Safe support bundle

Share only:

• CLI version
• command name and flags, with sensitive paths generalized
• exit code
• error.code, HTTP status, and request ID
• file counts, sizes, hashes, and secret key names only when your policy permits

Never share credential values, credentials.json, protected API responses, or raw environment files. A --dry-run --json report contains no secret values, but it does contain paths and key names that reveal architecture — treat it as internal.

Next steps

CLI referenceEvery error code, exit code, and the target chain behind `workspace_mismatch`.

Current versionsWhen the problem is release availability rather than runtime behaviour.

Secrets & protected filesWhat is safe to include in a support bundle, and what never is.

FAQQuestions that are about the product rather than a failure.