> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tempestai.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fixes for the most common Tempest problems, gathered from across the docs.

# Troubleshooting

Most Tempest problems fall into a small set of known shapes: a CLI that is not on `PATH`, a directory held open by another process, a pairing QR that expired. Start with the guide for the feature you are using, or jump straight to a quick fix below.

Nothing here? Search [open issues](https://docs.tempestai.dev/contributing/issues.md) — and if a fix is missing from this page, [open a feature request](https://docs.tempestai.dev/contributing/feature-request.md) so it gets added.

## Feature guides

> [card] [Installation](https://docs.tempestai.dev/installation.md)
>
> Installers, build-from-source, and platform prerequisites.

> [card] [Workspaces](https://docs.tempestai.dev/workspaces/creating.md)
>
> Sessions and worktrees that fail to start.

> [card] [Git worktrees](https://docs.tempestai.dev/git/worktrees.md)
>
> Warm pool, junctions, and cleanup problems.

> [card] [Agents](https://docs.tempestai.dev/agents/supported.md)
>
> Bundled agents, PATH checks, and policy blocks.

> [card] [Terminal](https://docs.tempestai.dev/terminal/overview.md)
>
> Rendering, scrollback, and restore issues.

> [card] [Token Intelligence](https://docs.tempestai.dev/token-intelligence/overview.md)
>
> Atlas indexing, daemons, and semantic search.

> [card] [Database branches](https://docs.tempestai.dev/database-branches/overview.md)
>
> Docker, base images, and branch startup.

> [card] [Mobile](https://docs.tempestai.dev/mobile/overview.md)
>
> Pairing, transports, and remote control.

> [card] [Themes](https://docs.tempestai.dev/themes/custom-themes.md)
>
> Custom themes and theme variables.

> [card] [Contributing](https://docs.tempestai.dev/contributing/overview.md)
>
> Building the repo and dev-environment issues.

## Quick fixes

Each entry gives the symptom, the usual cause, and the shortest fix. The link points at the page with full detail.

### Agent never appears after spawn

**Symptom:** You launch an agent and the terminal stays empty.

**Cause:** One of three things — the agent CLI is not on your `PATH`, its entry in `config/agents.json` was invalid and dropped silently, or project policy blocks the agent.

**Fix:** Work down the list:

1. Confirm the CLI resolves outside Tempest:

> [tab] Windows
>
> ```powershell theme={null}
> Get-Command claude
> ```

> [tab] macOS / Linux
>
> ```bash theme={null}
> which claude
> ```

2. Run `npm test` — it validates `config/agents.json`, so a silently dropped manifest entry shows up here. See [Supported agents](https://docs.tempestai.dev/agents/supported.md).
3. Check **Project Settings → Permissions/Agents** and make sure the agent is permitted for this project.

### Session lost after restart

**Symptom:** A reopened tab shows an empty terminal after an app restart.

**Cause:** Sessions persist in SQLite, but only agent sessions have their recent output restored from ring buffers. A plain terminal session keeps no scrollback, and conversation resumption only works for agents whose manifest declares `resumeArgs`.

**Fix:** Nothing is corrupted — the output simply was not captured. Prefer agent sessions for work you may resume, and pick agents that declare `resumeArgs` when continuation matters. See [App state internals](https://docs.tempestai.dev/internals/state.md) and [Agents](https://docs.tempestai.dev/agents/overview.md).

### "Database is locked" from Atlas

**Symptom:** Atlas reports `database is locked`.

**Cause:** Another process is indexing the same project. The index database runs in WAL mode, but a second writer can still collide with an active index run.

**Fix:** Let the other process finish, or delete `<project>/.tempest/atlas` and re-index with `remove_atlas_index`. See [Token Intelligence](https://docs.tempestai.dev/token-intelligence/overview.md).

> [!WARNING]
>
> Deleting `.tempest/atlas` removes the index, not your code — the next index run rebuilds it from scratch.

### Worktree creation fails

**Symptom:** Creating a session errors before an agent starts.

**Cause:** A duplicate worktree name, an empty repository tree, or (on Windows) a directory held open by another process.

**Fix:** Pick a different name. If the tree is empty, commit files first — Tempest rejects an empty checkout so agents never start in a blank repo. If a Windows directory is locked, close open sessions and retry; Tempest keeps a PID sidecar and can force-kill a locked worktree's processes. See [Worktrees](https://docs.tempestai.dev/git/worktrees.md).

### Push fails

**Symptom:** `git_push_current_branch` returns an error.

**Cause:** No `origin` remote, a dirty tree, or no network.

**Fix:** Add an `origin` remote, commit or clean your changes, and check connectivity, then push again. See [Push & PR](https://docs.tempestai.dev/git/push-pr.md).

### DB branch never appears

**Symptom:** The DB Clones panel stays empty after enabling database isolation.

**Cause:** Docker is not running (`db_check_docker` reports this), the project's base image has not been built, or the connection string points at a pooler host, which forces the `pgdump` snapshot method.

**Fix:** Start Docker, then build the base image in **Project Settings → Database**. See [Database branches](https://docs.tempestai.dev/database-branches/overview.md).

### Phone won't pair

**Symptom:** Scanning the QR code doesn't connect your phone.

**Cause:** The QR expired — codes have a 60-second TTL — or the phone is trying a transport your network doesn't allow.

**Fix:** Generate a fresh QR code and scan it promptly. If LAN pairing keeps failing, restart the relay with `TEMPEST_MOBILE_TRANSPORT=tunnel` to route through a Cloudflare tunnel. Admin rights and ETW tracing are not required for pairing. See [Mobile](https://docs.tempestai.dev/mobile/overview.md).

### Semantic search unavailable

**Symptom:** `atlas_semantic_search` is unavailable or returns nothing.

**Cause:** The one-time \~25 MB embedding model has not been downloaded.

**Fix:** In **Settings → Token Intelligence**, enable the semantic toggle; Tempest runs `download_atlas_model` and the model downloads once. See [Token Intelligence](https://docs.tempestai.dev/token-intelligence/overview.md).

### Keybindings not applying

**Symptom:** A keyboard shortcut does nothing or fires the wrong action.

**Cause:** Overrides live in runtime state, and a `null` binding disables an action entirely — easy to set by accident.

**Fix:** Open **Settings → Keybindings**, find the action, and reset it to the default. See [Keyboard shortcuts](https://docs.tempestai.dev/keyboard-shortcuts.md).

### Theme reset after update

**Symptom:** A custom theme disappears after updating Tempest.

**Cause:** Themes are discovered from `src/themes/**/theme.json` at build time, so a custom theme must be re-added after an update. Your selection persists in runtime state — the theme file is what's missing.

**Fix:** Re-add the theme under `src/themes/` and rebuild, then select it again. See [Custom themes](https://docs.tempestai.dev/themes/custom-themes.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.