# Troubleshooting Start every diagnosis with `wb view ` and `wb smoke `. 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 --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](/docs/cli/install#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: . 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 `, 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_... `, 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](/docs/cli/models#errors). ## 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 --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.