# Troubleshooting

> The refusals you may meet, and what each one means.

devpit refuses out loud rather than failing quietly, so the message usually is most of the answer. These are the ones you are most likely to meet, word for word.

## Installing and updating

### tmux is not installed, or not on PATH

Every terminal is a tmux pane, so without tmux there is no terminal at all. Install `tmux` from your system's packages, check that it is on your PATH, and open a terminal again.

### "devpit is damaged", or "cannot be opened"

macOS Gatekeeper refusing an app that is not signed with an Apple Developer ID and not notarised. That is the missing certificate talking, not the file. Open it once with right-click → **Open**, or clear the quarantine flag after checking `SHA256SUMS`. See [Installing](/docs/installing).

### an AppImage needs FUSE 2, which this machine does not seem to have.

The installer saying the AppImage will not start as it is. On Ubuntu and Debian, `sudo apt install libfuse2` — or, where apt exists, run the installer without `DEVPIT_FORMAT=appimage` and take the `.deb`.

### does not match its checksum — refusing to install it

The file that arrived is not the one the release published, so the installer stopped before installing anything. Run it again, and if it keeps refusing, do not install that file by hand.

### `<file>` is not signed by devpit's release key — refusing to install it

Where `minisign` is installed, the install line checks the signature as well as the checksum, and this one did not match. Do not install that file by hand. Without `minisign` it says "signature not checked" and goes on with the checksum alone.

### "Windows protected your PC"

SmartScreen stopping an installer that is not signed with a code-signing certificate. Check it against `SHA256SUMS`, then **More info** → **Run anyway**. See [Windows](/docs/windows).

### This copy is looked after by your system, so update it there.

devpit did not install this copy, so it will not replace it. Update it wherever it came from.

## Terminals

### this terminal is running `<command>`

devpit starts an agent by typing its launch line at a shell prompt, and this pane is busy. Let the command finish, stop it, or open another terminal with ⌘T (Ctrl on Linux and Windows).

### The default is not on this machine any more, so a new terminal opens a shell.

The **Default agent** in **Settings → Providers** is gone or switched off. Pick another one, or **No agent**, which is a plain shell.

### The island sits in the middle of the screen, as a window

On GNOME, or on Wayland without `gtk-layer-shell`, there are no layers to put it at the top, so it is a window that never takes focus, placed where the desktop puts it. Not a bug: **Settings → Notifications** says how it is drawn there. On GNOME on Wayland such a window took focus from devpit, so there the island stays off unless you turn on **Show the island anyway**. See [The island](/docs/island).

### no whisper on this machine — install whisper.cpp, or choose a service in Settings

A voice message with nothing to make it words. It was sent as a recording instead. Install a whisper, or choose a service in **Settings → Voice → Voice messages**.

## The board

### this step declares no spending cap, so it does not run

Every agent step needs a **Spending cap (USD)**, and one without it is refused before it can spend anything. Open the lane's step menu, choose **Edit `<step>`…**, and fill the field in.

### cannot be read

A badge on a lane: the step's stored settings are not valid, and devpit says so rather than quietly overwriting them. A card landing on that lane will fail. From the lane's step menu, point the lane at another step or at **Nothing**, and use **New step…** to replace it.

### A step that has already run on a card cannot be deleted

Its runs are that card's history, so the step stays. You will see "a card was run by this step and still shows it — set the lanes to run nothing instead", or "a card is running this step right now". Set each lane that uses it to **Nothing**.

### `<key>` is not a context key — the ones that exist are: …

A command step names a `{{key}}` that does not exist. It is refused when you save it, rather than running later with an empty value. Use one the message lists: `card`, `cardTitle`, `cardBody`, `branch`, `baseRef`, `project`, `worktreePath`, `projectPath`.

### preparing the worktree failed: `<command>` exited `<code>`

A card's new checkout could not be prepared, so the step never started. The problem is in the command that is named, not in the agent or the step.

### the chain stopped here — it had moved through too many lanes

A card moved through lanes set to advance on their own until devpit stopped it, and the bell says "A card stopped moving on its own". Look at where each lane sends a card that passes, and move this one by hand.

### `<card>` is ready for `<lane>`

Not a failure. The next lane's step is marked as having no undo, so devpit never moves a card into it on its own, even from a lane set to move cards **On its own**. Move it when you are ready.

### `<lane>` runs a step, and a card entering it starts work — ask the person to move it there

An agent or an orchestrator tried to move a card into a lane that runs a step. Entering such a lane starts work, so only you move a card there.

## Elsewhere

### It ran and left nothing devpit can read as a result. Exit code zero is not a pass.

A check with no verdict: the command ended, but nothing it left says what was checked. See [Reading a check](/docs/checks).

### nobody gave an agent the `<pane>` pane to drive

An agent asked about a browser pane that was not given to it. Driving is off by default. Turn on **Let an agent drive this page** in that pane's menu. See [Letting an agent drive a page](/docs/browser-agents).

### Tailscale refused to publish it

[Remote](/docs/remote) needs `tailscale serve`, which a user who is not Tailscale's operator may not run. Run `sudo tailscale set --operator=$USER` once, then turn Remote on again.

### this device may only watch — allow it to type on the machine

What a paired device may do is set on the machine. Tick **type** or **answer** beside it in **Settings → Remote**.

### this installation has no saved sign-in; open claude there to sign in

Plan limits are read with the Claude CLI's own sign-in, not your devpit account. Run `claude` for that installation and sign in. "the saved sign-in was refused" means the same thing, again. See [Usage and plan limits](/docs/usage).
