# Troubleshooting

> Fixes for common Helix failures: install and PATH problems, Node and CLI versions, deploy and build errors, local key-value resets, and access surprises.

When a Helix command fails, check versions first: `node --version` should print 24.18.0 or higher, and `helix --version` should print v0.85.0 or greater. This page collects the known failure modes across setup, local development, deploys, and identity, each with its cause and fix. If your problem isn't here, open your app in the [dashboard](https://app.helix.tray.ai), read the execution logs, and see [getting help](#getting-help).

## Setup and install

### helix: command not found

**Symptom:** your shell prints `helix: command not found`.

**Cause:** the CLI isn't installed globally, or your shell can't see the global npm bin directory.

**Fix:** install (or reinstall) the CLI, then check where it landed and which version answers:

```bash
npm install -g @trayai/helix-cli
which helix
helix --version
```

`which helix` should print a path inside your global npm bin directory. If it prints nothing, that directory isn't on your `PATH`: run `npm bin -g` to see where npm installs global binaries, add it to `PATH` in your shell profile, and open a new terminal. `helix --version` should print v0.85.0 or greater.

With pnpm: `pnpm add -g @trayai/helix-cli`. If a fresh terminal still can't find `helix`, you can run every command without a global install: `npx @trayai/helix-cli <command>`. The [quickstart](/documentation/getting-started/quickstart/) walks through the full install.

### Node.js version is too old

**Symptom:** the CLI or the SDK throws Node errors on install or on run, and `node --version` prints a version below 24.18.0.

**Cause:** both the Helix CLI and the Helix SDK need Node.js ≥ 24.18.0.

**Fix:** upgrade Node, then reinstall the CLI under the new version:

```bash
nvm install 24
npm install -g @trayai/helix-cli
```

Reinstall the project's dependencies too, so the SDK is rebuilt against the new Node: `npm install` inside the project.

## Runtime and deploy

### helix dev is not on port 3000

**Symptom:** you expect the app at `http://localhost:3000`, but nothing answers there.

**Cause:** `helix dev` serves on port 3000 by default, but when 3000 is taken it moves to the next free port.

**Fix:** read the dev server's startup output for the actual URL. To get a predictable port, stop whatever holds 3000, or choose one yourself:

```bash
helix dev --port 4000
```

The [CLI reference](/documentation/reference/cli/) lists the other `dev` flags.

### Deploy asks for a workspace every time

**Symptom:** every `helix deploy` stops and prompts you to pick a workspace, even though you picked one last time.

**Cause:** the workspace was chosen for that one deploy and never written to the project, so nothing persists the choice.

**Fix:** set the workspace once, by ID, then deploy:

```bash
helix workspace set <id>
helix deploy
```

`helix workspace select` prompts you with the list if you don't know the ID. You can also set it at scaffold time with `helix init my-app --workspace-id <id>`. Your Tray contact tells you which workspace you're provisioned in, and you have to be a member of it to deploy into it.

### Build failed on deploy

**Symptom:** `helix deploy` reports that the build failed, and the new version doesn't go live.

**Cause:** the project didn't compile, or the build hit an error the deploy summary only names in passing.

**Fix:** pull the full record for that deployment, which carries its status, any warnings, and the build errors:

```bash
helix deployment get <deploymentId>
```

The deploy output prints the deployment ID. Fix what the build reports, then deploy again.

### A deployed app returns errors

**Symptom:** the deploy succeeded, but requests to the live URL fail.

**Cause:** a runtime error in your function code.

**Fix:** open the project in the [dashboard](https://app.helix.tray.ai) and read its execution logs. There's one entry per HTTP request, and opening an entry shows the full trace: the operations that ran, the third-party calls they made, and the request and response payloads. Add `ctx.log` statements for more detail, or ask Claude to add them.

### Key-value data disappears between local runs

**Symptom:** you write values with `setItem`, restart `helix dev`, and they're gone.

**Cause:** this is expected. The local key-value store is held in memory and resets every time the dev server restarts.

**Fix:** nothing to fix locally. Only a deployed, provisioned project stores key-value data that survives. If you need data to persist while you're developing, deploy the project and test against the deployed app. The [key-value store guide](/documentation/guides/key-value-store/) covers the API.

### getItem returns null unexpectedly

**Symptom:** `getItem` hands back `null` for a key you're sure you wrote.

**Cause:** `null` means two different things: the key is missing, or the key exists and the stored value is `null`. You can't tell them apart from the return value.

**Fix:** ask whether the key exists before you read it:

```ts
if (await ctx.kv().hasItem('user:42')) {
  const value = await ctx.kv().getItem('user:42');
}
```

If `hasItem` returns `false`, the key was never written (or was removed). If it returns `true` and `getItem` still gives you `null`, the stored value really is `null`.

## Identity and access

### Cannot deploy, or no authentications available

**Symptom:** `helix deploy` refuses to run, or the project reports that no authentications are available to it.

**Cause:** both need an identity and a workspace. Either you aren't logged in, or you are logged in but no workspace is selected. Authentications belong to a workspace, so with none selected there are none to offer.

**Fix:** log in, then select a workspace:

```bash
helix login
helix workspace select
```

`helix whoami` confirms who you're logged in as. You can build locally with Claude without logging in, but deploying, using authentications, and managing workspaces all need it.

### Your login session has expired

**Symptom:** `helix` commands that authenticated fine before now fail to authenticate. `helix whoami` prints `Your saved Tray login is no longer valid. Run helix login.`

**Cause:** browser sign-in sessions last seven days from when you signed in, or less if your organization set a shorter timeout. Using the CLI does not extend them.

**Fix:** log in again and confirm your identity:

```bash
helix login
helix whoami
```

### A deployed app returns 403

**Symptom:** a colleague opens the app's URL and gets a 403 instead of the app.

**Cause:** they're a user in your organization, but the project's access setting doesn't include them.

**Fix:** open the project in the [dashboard](https://app.helix.tray.ai) and change who can reach it on its Access Control tab. Remember that a deployed app is never public: everyone who opens it has to be a Tray or Helix org user who has been granted access. [Identity and roles](/documentation/guides/identity-and-roles/) explains the three access settings.

### An admin can open an app I did not share

**Symptom:** an org admin opens your app even though you never added them to it.

**Cause:** the project's access setting is **Workspace**, which is the default. Workspace access includes org admins as hidden members, so they're already in the audience.

**Fix:** if that's not what you want, open the project's Access Control tab in the [dashboard](https://app.helix.tray.ai) and pick a narrower setting. [Identity and roles](/documentation/guides/identity-and-roles/) walks through what each one covers.

## Getting help

During early testing, raise issues in Slack in **#helix-early-testing**. For anything urgent, use **#product-hq**.

:::note
The canonical support channels are still being finalized. Until they're announced, the two Slack channels above are the right place to go.
:::

---

Canonical: https://helix.tray.ai/documentation/troubleshooting/
Any link on this page is available as markdown by appending .md to its URL.
Full corpus: https://helix.tray.ai/documentation/llms-full.txt