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

# Troubleshooting

> Diagnose and resolve common errors when using Nagare.

## Run nagare doctor

The first step is always:

```bash theme={null}
nagare doctor
```

The result lists each check with details. See the meaning of each item at [CLI Reference](https://docs.nagare.smtdfc.net/en/reference/cli.md#nagare-doctor).

## Common Errors

> [accordion] command not found: nagare
>
> The `$HOME/.local/bin` directory is not in your `PATH`. See [Add to PATH](https://docs.nagare.smtdfc.net/en/installation.md#add-to-path).

> [accordion] Gateway process: not running — no PID file found
>
> The gateway is not running. Open a terminal and run `nagare gateway start`, keep that terminal open.

> [accordion] Gateway HTTP reachable: cannot reach ...
>
> The gateway is not running or is using a different port. Check the `NAGARE_GATEWAY_PORT` variable and make sure port `9832` is not occupied by another program.

> [accordion] RSA keyring: error
>
> Nagare cannot access the operating system's keyring. On Linux, a Secret Service daemon (for example GNOME Keyring or KWallet) must be running and unlocked.

> [accordion] Module: nagare\_vector — missing
>
> The memory module is not installed. Run the installation script again.

> [accordion] Web interface reports not logged in or token invalid
>
> The token has expired (60 hours) or the key in the keyring has changed. Run `nagare web` to log in again, or create a new token with `nagare auth token` and paste it on the login page.

> [accordion] Nagare does not respond
>
> * Check that you have added a model provider and selected **Default model** in **Settings → General**.
> * Check your API key and Base URL. Use the model list feature to test the connection.
> * Check the gateway logs at `~/.nagare/logs/app.log`.

> [accordion] Tool rejected: approval is required but no approval channel is available
>
> The tool needs approval but no channel is available to receive the request. Open the conversation in the web interface or use Telegram so you can approve it.

> [accordion] Plugin does not run or is in failed state
>
> * Check the logs at `~/.nagare/logs/plugins/<package_name>.log`.
> * Check that any environment variables the plugin needs (for example `NAGARE_TELEGRAM_TOKEN`) were set **before** starting the gateway.
> * Executable checksum mismatch: reinstall the plugin package.

> [accordion] Plugin installation failed due to invalid signature
>
> The package was modified after signing, or was signed with a different key than the one in `~/.nagare/trusted`. See [Plugin Signing](https://docs.nagare.smtdfc.net/en/plugins/signing.md).

## Logs

| Component | Location |
| - | - |
| Gateway | `~/.nagare/logs/app.log` and the terminal output running `nagare gateway start` |
| Plugin | `~/.nagare/logs/plugins/<package_name>.log` |
| Module | `~/.nagare/logs/modules/` |

## Reporting Issues

Open an issue at [github.com/smtdfc/nagare/issues](https://github.com/smtdfc/nagare/issues), including the output of `nagare doctor` and the relevant log excerpt.


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