# 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:

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

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

```json
{"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](/reference/cli/#error-codes); 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](/reference/cli/auth/#if-auth-fails) |
| `forbidden` | Valid key, wrong workspace or role | [hlix auth](/reference/cli/auth/#if-auth-fails) |
| `missing_credential` | No key entered at the prompt | [hlix auth](/reference/cli/auth/#if-auth-fails) |
| `invalid_base_url` | `--base-url` is not HTTPS or loopback | [hlix auth](/reference/cli/auth/#if-auth-fails) |
| `workspace_mismatch` | An override contradicts the folder's binding | [CLI reference](/reference/cli/#where-a-command-points) |
| `workspace_required` | Nothing in the chain named a workspace | [hlix import](/reference/cli/import/#if-import-fails) |
| `not_initialized` | The folder is not bound to a project | [hlix push, pull & sync](/reference/cli/sync/#if-reconciliation-fails) |
| `already_imported` | The folder is bound; push instead | [hlix import](/reference/cli/import/#if-import-fails) |
| `scan_blocked` | The import scan found a blocker | [Import a project](/cli/import/#if-the-scan-blocks-the-import) |
| `conflict` | Both sides moved, or a compare-and-swap lost | [hlix push, pull & sync](/reference/cli/sync/#if-reconciliation-fails) |
| `approval_required` | The caller could not be asked | [hlix push, pull & sync](/reference/cli/sync/#if-reconciliation-fails) |
| `cancelled` | An interactive prompt was declined | [hlix push, pull & sync](/reference/cli/sync/#if-reconciliation-fails) |
| `not_found` | No such resource **in this workspace** | [hlix projects](/reference/cli/projects/#if-a-projects-command-fails) |
| `missing_argument` | A required positional was omitted | [CLI reference](/reference/cli/#if-a-command-fails-before-it-runs) |
| `invalid_usage` | Unknown flag, bad value, or too many arguments | [CLI reference](/reference/cli/#if-a-command-fails-before-it-runs) |
| `unknown_command` | No such command | [CLI reference](/reference/cli/#if-a-command-fails-before-it-runs) |
| `unreachable` | The API could not be contacted | [hlix status](/reference/cli/status/#if-status-reports-something-unexpected) |
| `rate_limited` · `server_error` · `not_implemented` | The API refused or failed | [API reference](/api/reference/#if-a-request-fails) |
**`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](/getting-started/install/#if-installation-fails) |
|  An install command that fails | [Current versions](/releases/availability/#if-a-version-looks-wrong) |
| The dry run reports blockers | [Move an existing project](/guides/quickstart/#if-the-dry-run-blocks) |
| A detected environment plan looks wrong | [Environment discovery](/cli/environment-discovery/#if-the-plan-is-wrong) |
| A secret is empty inside a task | [Secrets & protected files](/security/secrets/#if-a-secret-does-not-reach-the-workspace) |
| An imported skill, agent, or MCP server stayed inert | [Import trust model](/security/trust-model/#if-the-boundary-check-surprises-you) |
| A resource import was refused | [hlix skill, agent & mcp import](/reference/cli/resources/#if-a-resource-import-fails) |
| A task never starts, or names an unavailable harness | [Connect your agents](/guides/connect-agents/#if-a-task-will-not-start) |
| A task exists but will not run | [Tasks](/running/tasks/#if-a-task-will-not-run) |
| A cycle will not execute | [Cycles](/running/cycles/#if-a-cycle-will-not-execute) |
| Review evidence is missing or stale | [Reviewing output](/running/review/#if-review-fails) |
| An approval will not resolve | [Approvals](/running/approvals/#if-an-approval-will-not-resolve) |
| The workspace terminal will not open | [The Coding Workspace](/concepts/coding-workspace/#if-the-workspace-will-not-open) |
| A memory never reaches a run | [Context, memory & DNA](/concepts/context-memory/#if-memory-does-not-show-up-in-a-run) |
| GitHub, Linear, or Telegram will not connect | [Integrations](/integrations/#if-an-integration-will-not-connect) |
| An SDK call throws | [TypeScript](/sdk/typescript/#if-the-client-fails) · [Python](/sdk/python/#if-the-preview-client-fails) · [Go](/sdk/go/#if-the-preview-client-fails) |
| A generated client is missing an endpoint | [API reference](/api/reference/#what-is-not-here) |
| Behaviour changed after an upgrade | [Changelog](/releases/changelog/#if-an-upgrade-goes-wrong) |

## 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:

```bash
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](/cli/resources/#common-failures)).

### The package or Registry entry is missing

Use the exact version shown on the [MCP server page](/mcp/). A client that cannot resolve it is usually pinned to a version that was never published — check the pin against [Current versions](/releases/availability/).

### 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 reference](/reference/cli/)
  [Current versions](/releases/availability/)
  [Secrets & protected files](/security/secrets/)
  [FAQ](/guides/faq/)