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

# Troubleshoot Podium by layer

> Identify whether the server, daemon, repository, harness, or session is failing.

Start with the smallest layer that can explain the symptom. Preserve dirty work and logs before restarting or forcing a stop.

## Run the first checks

Check local processes, machine readiness, and recent logs before changing state:

```bash theme={"system"}
podium status
podium machine list
podium logs --pretty
```

| Symptom | First action |
| - | - |
| Web app does not open | Check server status and the configured port |
| Machine is offline | Check the daemon and its route to the server |
| Issue will not start | Check machine permission, repository, harness, and login state |
| Session is idle | Inspect session status and the latest turn |
| Session errored | Read the error before using `continue` |
| Update failed | Keep the current state directory and inspect updater logs |

## `podium` is not found after installation

The installer updates future login shells. Open a new shell or run:

```bash theme={"system"}
export PATH="$HOME/.local/bin:$PATH"
```

If that fails in a new shell, add `~/.local/bin` to the startup file your shell reads.

## A machine cannot pair or reconnect

Pairing codes are single-use and expire after one hour. Generate a new command in **Settings**, then **Machines**, then **Add machine**.

The daemon connects outward to the server. Confirm that it can resolve and reach the configured server URL. If a Cloudflare quick-tunnel URL changed, update the joined machine:

```bash theme={"system"}
podium set-server new_server_url
podium stop
podium
```

## A harness is missing or logged out

Re-run the machine probe:

```bash theme={"system"}
podium machine reprobe your_machine_name
podium machine show your_machine_name
```

Install or authenticate the native harness on that machine. Podium does not replace the harness's own account login.

## An issue cannot start

Check these conditions:

* The issue is not blocked by an open dependency
* The selected machine is online and usable
* The repository exists there or has a cloneable origin
* The selected harness is installed and logged in
* No conflicting worktree or branch already owns the target path

Use `podium issue show your_issue_ref` and `podium machine show your_machine_name` to inspect the exact state.

## A session appears unresponsive

Inspect its structured state and a short transcript window before stopping it:

```bash theme={"system"}
podium session status your_session_id
podium session read your_session_id --turns 8
```

Do not force-stop a session with unsaved changes. If the phase is retryable error, fix the reported cause and run `podium session continue your_session_id`.

## Collect diagnostics safely

Export recent crash events for support:

```bash theme={"system"}
podium logs export-crash --limit 100 --out podium-crash.json
```

Review the file before sharing it. Logs can contain repository paths, prompts, command arguments, hostnames, and error details.