Troubleshooting

Common problems and fixes. If yours isn’t here, please open an issue.

Logs

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:

& "$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:

& "$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.
• 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 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 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.