Troubleshooting

Find recovery steps for CLI errors, integrations, import integrity and cloud setup problems.

Find your error code or symptom below. The links lead to recovery steps for commands, integrations and project setup. Later sections cover import integrity, environment recreation and hosted MCP connections.

Prerequisites

Capture the command, installed version, exit code and JSON error:

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}}

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
`invalid_project_file`	`hlix.yml` or `hlix.local.yml` cannot be read	hlix init
`scan_blocked`	The import scan found a blocker	Move an existing project to hlix
`conflict`	Both sides moved, the folder is already bound, or an override contradicts its binding	hlix push, pull & sync
`approval_required`	The caller could not be asked	hlix auth logout
`cancelled`	An interactive prompt was declined	CLI reference
`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 request failed	API reference

approval_required means the caller could not answer a confirmation prompt; cancelled means a prompt was declined. Review the target and consequences before repeating the command with --yes.

By what you saw

Symptom	Fix lives at
`hlix: command not found`, or npm `E404`	Install the CLI
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 security
A resource import failed	hlix skill, agent & mcp import
Project work never starts	Connect your agents
A task exists but will not run	Tasks
A cycle will not execute	Cycles
Review or merge needs attention	Reviewing output
An approval will not resolve	Approvals
The Cloud Machine terminal will not open	Cloud Machines
A memory never reaches a run	Memories
GitHub, Linear, Slack or Telegram will not connect	Integrations
An SDK call throws	TypeScript · Python · Go
Behaviour changed after an upgrade	Changelog

Integrity and concurrency

Use the scan or synchronization result to identify what changed, then reconcile it before retrying.

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 over a trusted connection. If the hash, size, commit or manifest mismatch repeats, contact support with the request ID and error code.

The project has active tasks

A running cycle can advance the repository head while you work locally. Wait for a terminal status, then reconcile:

hlix tasks watch <task-id>
hlix sync

A protected-file error

Inspect the named path with ls -ld. Move or remove an unsafe local entry only after checking its contents, then retry. Pull recreates stored symlinks without modifying the files those symlinks point to.

Environment recreation

Check the project configuration when a Cloud Machine differs from your local environment.

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. Record the required setup and configuration in the repository so the next Cloud Machine starts consistently.

The official MCP server

Connect an assistant to the hosted endpoint at https://mcp.hlix.ai/mcp. See Connect your AI for client setup.

The client cannot connect

Use https://mcp.hlix.ai/mcp as the remote HTTP endpoint and complete the client’s sign-in flow.

A script or CI job gets 401

The API key is invalid, expired, or missing from Authorization: Bearer <key> (or X-API-Key: <key>). Create a new key on the API Keys page and check the header reaches the request.

Write tools are absent

A signed-in connection is read-only when write was unticked at sign-in. Reconnect with write access if you need it. API-key connections can expose write tools, but each operation still requires the caller’s workspace and project permissions.

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.