Help

Troubleshooting

Start every diagnosis with wb view <alias> and wb smoke <alias>. They show what the run will resolve and what is missing, without spending model tokens. smoke on e2b and daytona creates a billable sandbox.

The run looks stuck#

A headless run that seems slow with nothing happening is almost always waiting on a permission. Check wb ps --json for needs_input and pending_requests, or wb wait <id> --json, which exits 2 with the request. Answer it with wb answer. Repeated prompts for the same paths mean the Workbench's runner permissions are missing entries; report that to its author instead of approving everything.

Setup#

Symptom	Cause and fix
`wb: command not found` after installing	The install directory is not on `PATH`. Run `export PATH="$HOME/.local/bin:$PATH"` and add it to your shell profile.
`Runner CLI is unavailable: opencode`	Install the runner on the host for `local`, or use a runtime whose image contains it. See Install a runner.
`Required CLI tool is unavailable: X`	A declared tool is missing on the host or in the image. Install it, or use another declared runtime.
`Docker CLI is unavailable on the host`	Install and start Docker, or use another runtime.
`Workbench X does not declare runtime: Y`	Pick one of the runtimes listed.
`requires a GPU but none was found: <reason>. Pass --allow-unchecked-gpu to run on a GPU discovery cannot see.`	GPU discovery found no GPU. Fix the driver or install `nvidia-smi`. Pass the flag only when the host has the GPU.
`requires a GPU but the Docker daemon has no NVIDIA container runtime`	Install the NVIDIA Container Toolkit, run `nvidia-ctk runtime configure --runtime=docker`, and restart Docker. On macOS use the local runtime.
`Host Docker engine access requires explicit --allow-host-docker authorization`	The Workbench declares host Docker access. Grant it with `--allow-host-docker` only if you accept that it gives the run administrative access to your Docker daemon.
`A run started by an earlier version of Workbench is still active`	A detached worker from an older version still owns its files. Wait for it or stop it. The message names the run file to remove if the process is gone.
`Manifest spec N is not supported by this engine; upgrade wb`	Run `wb update`.

Sources and saving#

Symptom	Cause and fix
`Use a registry publisher/name, full HTTPS GitHub URL, or an explicit local path.`	A bare name is not a reference. Use `publisher/name`, a full HTTPS GitHub URL, or a path.
`Registry Workbench does not exist: org/name. Internal workbenches need a key for their organization`	Run `wb login --org <org>`, then add it again.
`Saved Workbench X has changed. Rerun with --force to replace it.`	Rerun `wb add` with `-f` if you want the change.

Running#

Symptom	Cause and fix
`wb run requires a task`	Pass a task, `--task`, `--task-file`, or `--stdin`.
`Session wb_... needs new input`	Use `wb send wb_... <text>`, or pass a task to `resume`.
`wb create requires an authoring brief`	Pass `--task`, `--task-file`, or `--stdin`, or use `--from`.
`No project "X". Did you mean "Y"?`	`--project` never creates a project. Use the suggestion, or run `wb project create "X"`.
`Missing required environment variable: NAME`	The Workbench requires `NAME`. Provide it in the environment or with `--env-file`.
`The daytona runtime does not support runners that read from standard input yet`	Update `wb`. Current engines run OpenCode, Pi, and Claude Code on Daytona. Claude Code needs 2.1.318 or newer in the image.
`The daytona runtime needs an image. Set runtimes.daytona.image.`	The Daytona entry needs a published image.

Credential errors and their fixes are on Models and connections.

Studio#

Symptom	Cause and fix
`Docker isn't running. Start Docker and run wb studio again.`	Start Docker, then rerun `wb studio`.
Docker is using Windows containers	Switch Docker Desktop to Linux containers.
`Studio image X does not match this version of wb`	Drop `--image` to use the default image, or update `wb`.
The open link says it was already used	Run `wb studio` again for a fresh link.

Workers#

Symptom	Cause and fix
`Sign in first with wb login`	Run `wb login` on this machine.
`This machine is already the worker mini. Run wb worker remove first.`	Leave out `--name`, or remove the worker first.
`wb worker is not supported on Windows yet`	Use macOS or Linux.

Workspaces#

Docker mounts the workspace at /workspace. A git worktree does not work there, because its .git file points at a parent repository that is not mounted. Use a full clone, such as git clone --local, and fetch its branch back.
Docker containers and the host conflict over node_modules built for different platforms. Give a containerized run its own clone.
E2B and Daytona edits stay in an outcome until wb outcome <id> --apply writes them to your workspace.

Cleanup#

Runs that start servers can leave processes behind. After a session ends, check for orphaned dev servers before starting more. wb clean previews old run data; add --apply to delete it.