Troubleshooting — Stackbone

A workspace boots a lot of moving parts — a local datastore, durable workflows, and one or more agents. This page catalogues the failures you will actually 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. Reach for it before anything else:

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.
Map code to an exit code. Shell scripts can branch on $? instead of parsing text. See the full table at Configuration → Exit codes.
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 is what you need to see why a stage is stuck.
Read the offline copy. stackbone docs cli prints this reference without a network round-trip; it ships with the version of the CLI you have installed.

Reading a boot failure

stackbone dev walks a fixed sequence of stages, each painted as its own line in the spinner UI:

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/`)
`workflows`	Compiles your durable workflows
`agent`	Boots the durable workflow world (the worker that drains workflow runs)
`emulator`	Starts the local control plane, bundles and mounts every agent under `deep-agents/`, and serves the chat + workflow routes
`tunnel`	Opens the public URL that fronts your local workspace

The workspace is discovered by convention: every folder under deep-agents/ with an index.ts is one agent, and every workflows/<name>.workflow.ts is one durable workflow. Agents run in-process as part of the emulator stage, there is no per-agent process to build or start separately, so a broken agent (a bad import, a syntax error in its index.ts) fails the emulator stage rather than a dedicated agent stage. When a stage fails, the spinner turns that line red and the structured error tells you which one and why.

`stackbone dev` failures

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 — inspect the Postgres or Redis container under .stackbone/dev to see the underlying error, then re-run.

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 <n>. Your agents always pick a free port automatically, so you only ever need to relocate the control plane.

An agent fails to build

Symptom: the emulator stage fails, with an error naming one of your deep-agents/<name>/index.ts files, or "Cannot resolve esbuild from the workspace".

Cause: your project's dependencies are not installed, so the agent runtime library (or its model provider packages) can't be resolved at build time, 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, then re-run stackbone dev. If the error names a specific file, fix that agent and restart.

"Failed to boot the workflow world"

Symptom: the agent stage fails with this message.

Cause: your project's dependencies are not installed, so the workflow runtime worker cannot boot.

Fix: install your workspace dependencies, then re-run stackbone dev.

Workflows are missing

Symptom: stackbone dev starts fine, but stackbone workflows list and stackbone runs list come back empty.

Cause: the workflows stage soft-failed. A workflow build error does not crash the session — your agents are unaffected and the workspace simply starts without workflows, so the control plane never mounts the workflow routes.

Fix: re-run with --verbose and look for the Workflow build failed — starting WITHOUT workflows warning. The cause follows it. Fix the workflow and restart. See Workflows for the authoring contract behind the build.

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. Three failures map to three 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 and re-run once it recovers

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.

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 <id>.

`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 <id>` 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`).

dev_not_running is the single most common surprise on the new command surface: a runs / logs / workflows command run in a project where nothing is live fails fast with exit 3 rather than silently hanging. The fix is always the same — start stackbone dev, or target a cloud install with --agent.

The durable-workflow tooling (stackbone workflows list, stackbone workflows schema) is exercised through stackbone dev today. Pointed at an installation that does not serve the workflow routes, those commands come back empty rather than erroring.

`stackbone publish` failures

stackbone publish compiles your whole workspace once, on your machine, into a single bundle. Every guardrail below aborts before a bundle is produced — a failed publish ships nothing, which is the point: a publish error is always better than a crash-loop in production. Each abort prints the exact fix; here is what each one means.

`@stackbone/sdk` inlined into an agent build

stackbone publish failed: deep agent "<name>" inlined @stackbone/sdk into its build.

A workspace agent must keep @stackbone/sdk external, so it resolves to a single copy at runtime. A second copy gives the agent its own ambient context and per-run logs arrive empty. defineDeepAgent from @stackbone/sdk/deep keeps the SDK external for you automatically; this error only appears if something in your build pipeline forces it to inline anyway (for example a bundler config outside stackbone publish re-processing the output). Remove whatever is re-bundling @stackbone/sdk and re-publish.

Native dependencies rejected

stackbone publish failed: native dependencies detected in deep agent "<name>".

The workspace runtime runs pure-JS agents only. A dependency with native bindings (.node files) is rejected with the offending package name. Remove the native dependency from that agent.

No agents declared

This workspace declares no deep agents (none found under deep-agents/*/index.ts) — a workspace bundle needs at least one deep agent.

The workspace has no agents, there is no deep-agents/<name>/index.ts to discover. A workspace bundle needs at least one, so add one (for example stackbone add agent <name>, which scaffolds deep-agents/<name>/) and re-publish.

An agent's build failed

esbuild failed for deep agent "<name>": …

One agent's index.ts failed to bundle. The message carries the underlying esbuild error (a syntax error, a missing import); fix it and re-publish.

Incompatible `@stackbone/sdk`

@stackbone/sdk@<version> is not compatible with this CLI, which supports >=0.1.0 <0.2.0 (built against 0.1.0).

Each CLI build supports one minor line of @stackbone/sdk. stackbone publish blocks when the version installed in your project falls outside that line, because an incompatible SDK is what would ship to cloud. Pin the SDK to a supported version and reinstall:

pnpm add -E @stackbone/sdk@<version>

The same check runs at the start of stackbone dev, but there it only warns and keeps the local loop running. 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 silently 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 and the Workflow SDK 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 one-line banner to stderr when a newer @stackbone/cli is published. 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), or silence it with STACKBONE_NO_UPDATE_CHECK=1. See 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. Only the CLI is gated: the dashboard, SDK clients, and health checks are never turned away. Run the suggested upgrade, then retry.