# Troubleshooting

Common problems and fixes. If yours isn't here, please
[open an issue](https://github.com/Areshkew/nana/issues).

## Logs

| What | Where |
| --- | --- |
| Server | `server.log` in the [profile folder](https://nana.areshk.dev/docs/features/server.md#files) |
| Desktop app | Start it with `NANA_DIAGNOSTICS=1` to write `app-diagnostics-<pid>.log` to the profile folder |
| Kibbles | **Settings → Kibbles →** the kibble **→ Reveal log** |
| CLI | Printed in the terminal |

`nana --build-info` and `nana server status` show the versions in use.

## The app doesn't open

Usually `settings.toml` has an error or an unknown key. Start the app from a
terminal to see why:

```powershell
& "$env:LOCALAPPDATA\Programs
ana-desktop\current
ana-app.exe"
```

Fix the line it names, or move `settings.toml` out of the profile folder to
start with defaults.

## The server won't start

If `nana` reports `request timed out`, run the server in the foreground to see
the error, often a typo in `server.toml`:

```powershell
& "$env:LOCALAPPDATA\Programs
ana-desktop\current
ana-server.exe"
```

## `nana` is not found, or is the wrong version

The installer's **Command line tool on PATH** feature, or **Install Command
Line Tool…** in the app, adds the installation's `current` folder to your
user `PATH`. Open a new terminal afterwards: a terminal that was already open
keeps its old `PATH`.

If `nana --version` reports an older version than the app you installed, an
earlier installation's `nana` comes first on your `PATH`.

## A remote server won't connect

- **Host key not trusted:** run `ssh <host>` once and accept the key.
- **Login refused:** check that `ssh <host>` works with your key or agent. Only
  the desktop app supports passwords.
- **Nana isn't installed:** install it from the **Remote** section, or run the
  installer there. See [Remote servers](https://nana.areshk.dev/docs/features/remote-servers.md).
- **Incompatible version:** install the same version on both computers. If the
  version is right but the old server is still running, run
  `pkill -x nana-server` there. This ends its terminals.
- **Terminals end when SSH disconnects (Linux):** run `loginctl enable-linger`.

## No agent notifications

- Allow notifications in **Settings → System → Notifications → Nana**.
- Toasts are filed under the installed app's identity and the
  installer registers it. A Nana that Windows does not know as an app reports
  notifications as unavailable rather than dropping them quietly.
- Nana doesn't notify for the pane you're looking at, or for detached
  terminals.
- Recognition is best effort. `nana activity list` shows what the server sees.

## Git or AI actions are disabled

- Install and sign in to a supported [AI tool](https://nana.areshk.dev/docs/features/git.md#ai-tools) in
  a terminal, then try again.
- Pull request features need `gh` installed and signed in on the project's
  server: `gh auth login`.
- AI actions run on this computer. For a remote project, the same folder must
  exist here.
- Actions are disabled on a clean tree, a detached HEAD, during conflicts, or
  while another action runs.

## Keys don't work as expected

- Key bindings in **Settings → Terminal → Key bindings** win over app
  shortcuts while a terminal is focused.

## Start fresh

1. Stop the server, which ends every terminal: `nana server stop --force`.
2. Quit Nana.
3. Move the [profile folder](https://nana.areshk.dev/docs/features/server.md#files) somewhere else.

`~/.config/ghostty` is not touched.

## Reporting a bug

Include your Windows version, the output of `nana --build-info`, steps
to reproduce, and the relevant lines of `server.log`.