Troubleshooting

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, read the execution logs, and see 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:

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

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:

helix dev --port 4000

The CLI reference 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:

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:

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

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:

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:

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 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 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 and pick a narrower setting. 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.