# Troubleshooting

## In-TUI Diagnostics

Press `d` when a server is selected to run a quick diagnostic probe over SSH.

The overlay displays:

- Kernel version and OS info
- CPU model and core count
- Load average (1 min, 5 min, 15 min)
- RAM usage bar (used / total)
- Disk usage bars for `/` and any extra paths in `probe_filesystems`
- A ⚠ warning for any configured filesystem that is not mounted

The probe uses the current connection mode (Direct/Jump) — Wallix is not supported.

## Verbose Mode

Press `v` in the TUI (or pass `--verbose` on the CLI) to enable verbose SSH output. The raw `ssh -v` output is shown in the detail pane after connecting, which exposes handshake details, key negotiation, and authentication steps.

## Persistent State (`~/.susshi_state.json`)

susshi writes state to `~/.susshi_state.json` after each session. The file contains:

| Key | Description |
| --- | --- |
| `favorites` | Set of server names marked as favorites |
| `expanded_items` | Set of group/environment names that are expanded in the tree |
| `sort_mode` | Current sort (alphabetical or recent-first) |
| `last_seen` | Map of `server_name → ISO timestamp` of last connection |
| `command_history` | Last 100 ad-hoc commands (deduplicated) |
| `tunnel_overrides` | User-created or user-edited tunnels per server |

To reset all state: `rm ~/.susshi_state.json`

To reset only tunnel overrides without losing favorites, edit the file and clear the `tunnel_overrides` key.

## Common Issues

### Connection fails immediately

1. Enable verbose mode (`v`) and retry — the SSH handshake error appears in the detail pane.
2. Check that `ssh_key` exists and is readable (`ls -la ~/.ssh/id_ed25519`).
3. If using jump mode, verify the jump host is reachable independently: `ssh jump-user@jump.example.com`.
4. If `use_system_ssh_config: true` is set, check `~/.ssh/config` for conflicting `Host` blocks.

### Config file not loading

Run `susshi --validate` to check all config files for syntax errors, unknown fields, and unresolved includes. Errors and warnings are printed with file names and line numbers.

### Wallix connection hangs or shows the raw menu

See [docs/wallix.md](wallix.md) for the full troubleshooting guide.

### Clipboard copy (`y`) shows a fallback overlay

The clipboard backend is unavailable. Install the required tool for your environment:

- X11: `xclip` or `xsel`
- Wayland: `wl-clipboard` (provides `wl-copy`)
- macOS: built-in (should work out of the box)

The fallback overlay displays the full SSH command — select and copy it manually.

### TUI looks garbled or colors are wrong

susshi requires a **truecolor terminal** (24-bit color). Verify with:

```bash
echo $COLORTERM   # should output "truecolor" or "24bit"
```

Common terminals with truecolor: Alacritty, kitty, WezTerm, iTerm2, modern GNOME Terminal.

### Mouse click does not work

Press `M` to toggle mouse capture. When mouse capture is disabled, terminal text selection works normally but TUI click events are not processed.
