--- title: 'Troubleshooting' description: 'Diagnose and fix the common stackbone dev and agent-runtime failures, keyed on the error codes the CLI emits.' position: 11 --- # Troubleshooting > A workspace boots a lot of moving parts: a local datastore, durable > [workflows](/docs/sdk/workflows/overview), and one or more > [agents](/docs/sdk/agents/overview). This page catalogues the failures you are > likely to hit, keyed on the `error.code` strings and exit codes the CLI > emits, so you can branch on a single value instead of reading a stack trace. ## The diagnostic loop Every command supports the same four-step loop. Run it before anything else: 1. **Re-run with `--json`.** Errors come back as a structured envelope: `{ "error": { "code", "message", "suggestion" } }`. The `code` is stable across releases and the `suggestion` is the next command to try. 2. **Map `code` to an exit code.** Shell scripts can branch on `$?` instead of parsing text. See the full table at [Configuration → Exit codes](/docs/cli/reference/configuration#exit-codes). 3. **Escalate the logs.** Set `STACKBONE_LOG_LEVEL=debug` to surface the structured logs on stderr. When a boot _stage_ hangs, escalate further with `--verbose` (or `STACKBONE_VERBOSE=1`): that swaps the per-stage spinner UI for the raw firehose, including the container engine's own output, which shows why a stage is stuck. 4. **Let your coding agent read these pages.** Run `stackbone docs` for the connection details of the documentation MCP server. Once the agent is connected it searches this site by question and reads the page it needs, including this one. ## Reading a boot failure `stackbone dev` walks a fixed sequence of stages, and the spinner UI paints one line per stage. The `emulator` stage is the exception: it runs in the listed order but draws no line of its own, so a failure there arrives as the error envelope rather than a red spinner. | Stage | What it does | | --------------------- | --------------------------------------------------------------------------------------------- | | `docker` | Brings up the local datastore: Postgres, Redis and an S3-compatible store | | `platform-migrations` | Applies the runtime's own schema | | `creator-migrations` | Applies your workspace's schema (`src/schema.ts` → `.stackbone/migrations/`) | | `emulator` | Starts the local control plane and begins serving | | `tunnel` | Opens the public URL that fronts your local workspace | | `workflows` | Compiles your durable workflows | | `world` | Boots the durable workflow world (the worker that drains workflow runs) and mounts its routes | | `deep-agents` | Bundles and registers every agent under `deep-agents/` | The order matters: everything Stackbone owns (the datastore, the schema, the control plane and the tunnel) comes up **before** the CLI compiles or runs anything you wrote. Even a workspace that cannot start yet leaves you with a reachable control plane and a working link. The CLI discovers the workspace by convention: every folder under `deep-agents/` with an `index.ts` is one agent, and every `workflows/.workflow.ts` is one durable workflow. Agents run **in-process** inside the control plane, and there is no per-agent process to build or start, so a broken agent (a bad import, a syntax error in its `index.ts`) fails the `deep-agents` stage without taking the session down. When a stage fails, the spinner turns that line red and the structured error tells you which one and why. The CLI skips stages you do not use: no workflows means no `workflows` or `world` line, and no `deep-agents/` folder means no `deep-agents` line. The `tunnel` stage always runs, because the public tunnel is mandatory. ## `stackbone dev` failures ### This directory is not linked to an agent **Symptom:** `stackbone dev` exits before any stage runs with `no_project` and "No project linked in this directory, and nothing here can ask which agent it is." **Cause:** the project has no `.stackbone/project.json` and this run cannot prompt for one. `.stackbone/` is gitignored, so a project cloned from someone else's repository always arrives unlinked, and a run without a terminal (or one with a `CI` environment variable, `--yes` or `--json`) has nobody to ask. **Fix:** run `stackbone dev` once from a terminal and pick the agent. It writes the link, and every later run reuses it, scripted or not. To link without a prompt, write `.stackbone/project.json` yourself; `stackbone agents get ` prints the agent id it needs. Reaching for `stackbone init` here is the common mistake: it registers a new agent and scaffolds over the project you were handed. Full contract: [A project that arrived without a link](/docs/cli/guides/local-development#a-project-that-arrived-without-a-link). ### Docker not running, or the datastore is unhealthy **Symptom:** the `docker` stage fails, or `platform-migrations` / `creator-migrations` fail with a connection or migration error. **Cause:** the container engine is not running, or the local Postgres / Redis container is unhealthy. **Fix:** make sure your container engine is running, then re-run `stackbone dev`. When a migration stage fails, the CLI's suggestion points you at the local container logs. Read them from the generated stack, then re-run: ```sh cd .stackbone/dev && docker compose logs postgres ``` ### Port already in use **Symptom:** the `emulator` stage fails because its port is taken. **Cause:** the local control plane defaults to port `4242` and something else already holds it (often a previous `stackbone dev` that did not shut down). **Fix:** free the port, or move the control plane with `stackbone dev --port `. Your agents run in-process inside that control plane, so its port is the only one to relocate. ### Nothing of yours started **Symptom:** `stackbone dev` finishes, the emulator and tunnel are up, but the `workflows`, `world` and `deep-agents` stages never ran. The CLI printed "Your workflows and agents are not running yet". **Cause:** the **boot gate**. This deployment has no [model provider](/docs/cli/guides/local-development#model-provider) configured and nobody has been through the first run, so the boot held your code back rather than failing every agent that names a model. **Fix:** open the Studio link the CLI printed and finish the guided setup. Your workspace starts the moment you save, with no restart. If the link is unreachable, export the endpoint and run `stackbone dev` again: ```sh export MODEL_PROVIDER_BASE_URL=https://openrouter.ai/api/v1 export MODEL_PROVIDER_API_KEY=sk-... # omit for a keyless local gateway ``` Full contract: [The first run](/docs/cli/guides/local-development#the-first-run). ### An agent is waiting for a model provider **Symptom:** the agent appears in Studio and in `GET /api/discovery`, but Studio marks it **degraded** and chatting with it returns `503` instead of an answer. **Cause:** the agent declares its model as a bare id and no model provider resolved, so the runtime could not build its graph. This is a configuration gap. **Fix:** configure a model provider (Studio's **Model provider** screen, or the environment variables above). Saving re-registers every degraded agent in place. An agent that stays degraded afterwards carries a different reason, which Studio shows on the agent's own screen. ### An agent fails to build **Symptom:** the `deep-agents` stage fails, with an error naming one of your `deep-agents//index.ts` files, or "Cannot resolve esbuild from the workspace". **Cause:** you have not installed your project's dependencies, so the build cannot resolve the agent runtime library (or its model provider packages), or the agent's `index.ts` itself has a syntax or import error. **Fix:** install your workspace dependencies (`pnpm install` from the project root) so every agent can resolve its runtime library. The session stays up while you fix it. Saving the file re-bundles that agent in place, with no restart. If the error names a specific file, fix that agent and save. ### "Failed to boot the workflow world" **Symptom:** the `world` stage fails with this message. **Cause:** you have not installed your project's dependencies, so the workflow runtime worker cannot boot. **Fix:** install your workspace dependencies, then re-run `stackbone dev`. ### A workflow will not start **Symptom:** `stackbone workflows list` shows the workflow, but `stackbone workflows start ` and `POST /api/workflows//start` come back `503` with a reason instead of a run id. **Cause:** that workflow failed to compile. A workflow build error leaves the session and the sibling workflows running: the ones that compiled still serve, and the CLI registers each broken one as **degraded** so the catalogue can still name it. A degraded entry answers `503` with a reason. A typo in the name answers `404`. **Fix:** re-run with `--verbose` and look for the `Workflow "" failed to build and is listed as degraded` warning. The cause follows it. Fix the file and save: the workflow watcher recompiles and remounts the set in place. See [Workflows](/docs/sdk/workflows/overview) for the authoring contract behind the build. ### No workflows at all **Symptom:** `stackbone dev` starts fine, but `stackbone workflows list` and `stackbone runs list` come back empty. **Cause:** the `workflows` stage _soft-failed_ before any workflow compiled, so the session started **without** workflows and the control plane never mounted the workflow routes. Your agents are unaffected. **Fix:** re-run with `--verbose` and look for the `Workflow build failed, starting WITHOUT workflows` warning. The cause follows it. Fix the error and restart. ### The tunnel will not open The public tunnel is **mandatory** (there is no opt-out flag) so its grant flow is a common boot blocker. Four failures map to four error codes: | `error.code` | Meaning | Fix | | ------------------------------ | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `auth_required` | No active session, or the control plane rejected it | Run `stackbone login`, then re-run | | `workspace_tunnel_cap_reached` | Your workspace already has the maximum active tunnels | Stop another `stackbone dev` session, or wait for an existing grant to expire | | `tunnel_relay_unhealthy` | The tunnel relay itself is down and cannot mint a grant | Check [status.stackbone.ai](https://status.stackbone.ai) and re-run once it recovers | | `generic` | "`frpc` is not installed or not on PATH": the auto-fetch could not run | Install `frpc` yourself and point `STACKBONE_FRPC_BIN` at it, see [Using a system `frpc` binary](/docs/cli/guides/local-development#using-a-system-frpc-binary) | The CLI retries `tunnel_relay_unhealthy` and `generic` on its own before the command gives up, so a single flap costs you nothing. It does not retry `auth_required` or `workspace_tunnel_cap_reached`, because a retry cannot fix either one. ### Native Windows shell **Symptom:** the CLI refuses to start with a banner about unsupported shells (`error.code` is `unsupported_platform`). **Cause:** you are running from a native Windows shell (PowerShell or CMD), which lacks the unix utilities the dev boot relies on. **Fix:** run the CLI from WSL2 or Git Bash instead. ### Ctrl-C does not stop `stackbone dev` in Git Bash **Symptom:** the dev session keeps running after Ctrl-C, and you have to close the terminal to stop it. Git Bash only. **Cause:** older Git Bash terminals run the CLI without a real pseudo-terminal, so the keystroke never reaches the process. The CLI re-launches itself under `winpty` to fix that, and `winpty` is not on your `PATH`. **Fix:** run `winpty stackbone dev`, or use Windows Terminal or WSL2, where Ctrl-C already works. Every other command is unaffected: only `dev` is long enough to need the interrupt. ## Command-targeting failures The Studio surface commands (`runs`, `logs`, `workflows`, `hitl`, `config`, `secrets` and friends) target the **local-dev installation** of your project by default, and a running cloud installation when you pass `--agent `. | `error.code` | Exit | Meaning & fix | | ------------------------ | ---- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `dev_not_running` | `3` | The command targeted your local-dev install but no `stackbone dev` is live. Start `stackbone dev` from this project, or pass `--agent ` to hit a cloud install instead. | | `auth` | `2` | Not logged in or the session expired. Run `stackbone login`. | | `not_found` | `4` | The targeted workspace, run or resource does not exist. | | `permission` | `5` | You are authenticated but not allowed to act on that resource (also raised when a destructive verb runs without `--yes`). | | `runtime_not_configured` | `4` | The `--agent ` you targeted has no registered deployment, so there is no runtime to answer. Deploy the box, then register it with [`stackbone link`](/docs/cli/reference/link). | `dev_not_running` is the most common surprise on this command surface: a `runs` / `logs` / `workflows` command run in a project where nothing is live fails fast with exit `3` rather than hanging. Start `stackbone dev`, or target a cloud install with `--agent`. The durable-workflow tooling (`stackbone workflows list`, `stackbone workflows schema`) runs against `stackbone dev` today. Pointed at an installation that does not serve the workflow routes, those commands come back empty rather than erroring. ## Incompatible `@stackbone/sdk` > `@stackbone/sdk@ is not compatible with this CLI, which supports >=0.3.0 <0.4.0-0 (built against 0.3.1).` Each CLI build supports one minor line of `@stackbone/sdk`. `stackbone dev` checks the version installed in your project on boot and warns when it falls outside that line, then keeps the local loop running. Pin the SDK to a supported version and reinstall: ```sh pnpm add -E @stackbone/sdk@ ``` If the SDK is not installed at all, the message tells you to run `pnpm install` first instead. A scaffolded project pins the SDK exactly (no caret), so a stray `pnpm update` cannot move it off the supported line. ## Checking a deployed workspace's health A running workspace exposes two probes you can hit directly when a deployment reports as degraded: | Endpoint | Returns | | ------------- | ---------------------------------------------------------------------------------------- | | `GET /live` | Instant `200`, the process is up. Use it for liveness checks. | | `GET /health` | Deep `200`/`503` with `checks: { database, redis }`, tells you _which_ subsystem failed. | When `/health` returns `503`, read the `checks` object: `database` covers your Postgres connection and `redis` covers the durable workflow backend. For the durable-execution model behind these surfaces, see [Agents](/docs/sdk/agents/overview) and the [Workflow SDK docs](https://workflow-sdk.dev/docs). ## Keeping the CLI up to date Two independent signals tell you the CLI is behind, one soft and one hard. A newer release is out (soft). About once a day the CLI checks the npm registry in the background and prints a short banner to stderr when it finds a newer `@stackbone/cli`. It never blocks a command or changes an exit code. Upgrade with the command the banner prints (it tracks your release channel, so a prerelease install is told to upgrade on `@alpha`, never `@latest`). The banner stays quiet on its own in `--json` mode, in CI, and when stdout is not a terminal. Silence it everywhere with `STACKBONE_NO_UPDATE_CHECK=1`. See [Configuration → Environment variables](/docs/cli/reference/configuration#environment-variables). Your CLI is no longer supported (hard). The control plane rejects a CLI older than the minimum version it accepts. The failure comes back with `error.code` `cli_upgrade_required` and exit code `1`, and its `suggestion` field carries the exact upgrade command to run. The control plane gates the CLI only, and lets the dashboard, SDK clients and health checks through. Run the suggested upgrade, then retry. ## See also - [Configuration](/docs/cli/reference/configuration#exit-codes): the `--json` envelope and the exit-code table. - [Local development](/docs/cli/guides/local-development): the full `stackbone dev` loop. - [Commands](/docs/cli/reference/commands): every command and its verbs.