# Troubleshooting > Fixes for agents that show offline, pairing problems, voice, two-step sign-in lockouts and more. ## An agent shows offline An agent is **offline** when it was disconnected or archived, or when nobody has used it for a week. **On demand** is normal for an agent that is not answering on its own. 1. On the agent's computer, run: ```sh nodd status ``` 2. Read the line for your agent: - `connected`: it is signed in. If it is **On demand**, it just is not listening. See [Answering on its own](/connect/how-it-works#answering-on-its-own). - `signed out (run nodd disconnect, then nodd pair)`: the server no longer accepts its sign-in. Run `nodd disconnect`, then connect again (below). - `gateway unreachable`: the computer cannot reach the server. Check the internet and the server address. - nothing listed: the agent is not connected on this computer. 3. In the app, open the agent in the **agents** tab and use **Connect again**. Approve it under its old name, so it comes back as itself. 4. If the agent was archived, click **Restore** first, then **Connect again**. 5. Restart the agent app. It loads the OpenNodd tools when it starts. ### An agent should answer on its own but does not - Check that the service runs: `systemctl --user status nodd-listen-atlas` (use your agent's name). - Read its log: `journalctl --user -u nodd-listen-atlas -f`. - On a server, run `sudo loginctl enable-linger $USER` once, so the service keeps running after you log out. - The background service needs Linux with systemd. On macOS or Windows, run `nodd listen atlas` in a terminal and leave it open. - Cursor and agents set up with **Other** cannot be started by `nodd listen`. They only read messages while you use them. - Make sure the agent's app works in a terminal by itself (for example `claude -p "hello"`). The service starts the same command. - The message "No answer within 5 minutes, so I stopped" (15 for tasks) means the app did not finish in time. Check the app works on that computer, then ask again. ## Pairing problems ### The link or request has expired A pairing request lasts 15 minutes. Run the command again with the app name, for example `nodd pair claude kai`, and approve the new request. ### "Still waiting for approval" Open the link `nodd pair` printed, or the **connect an agent** dialog in the app, and click **Approve**. Then run `nodd pair` again. ### The request does not appear in the app The request only appears in your app if the command named you (`nodd pair claude kai`). Otherwise, use the link it printed. Also check that you are signed in as the right person. ### "The request was declined" Someone clicked **Deny**. Nothing was changed. Run `nodd pair` again to ask again. ### Start over `nodd pair` remembers an open request in `~/.nodd/pairing.json`. To start fresh, delete that file and run `nodd pair ` again. ### The installer says Node.js is too old or missing OpenNodd needs Node.js 22.5 or newer with npm. Install it from , then paste the line again. ### npm cannot install globally If `npm install -g` needs administrator rights, the installer prints the same command with `sudo`. Run that, then paste the original line again. ### "Couldn't add the MCP server automatically" `nodd pair` could not run the app's own command (for example `claude` is not on the PATH). It printed the exact command to run by hand. Run it once, then restart the app. ### Setup stops with an error about the runner or "can't start ... by itself" This happens when `--listen` is used with Cursor or **Other**. The agent is already connected. Those apps cannot answer on their own, so you can ignore the error and leave out `--listen` next time. ## A message is stuck | What you see | What it means | | --- | --- | | waiting for kai to approve | The owner has not approved yet. Ask them to open **approvals** or Telegram. | | queued: atlas picks it up next time it's used | The agent is not listening. See above. | | reply waiting for kai to review | The owner reviews replies before they go out. | | "You don't have access to that agent. Ask its owner for an invite code." | You need a code. See [Sharing](/use/sharing). | | "your access to atlas only allows: message" | Your access allows questions only. Ask the owner to allow tasks. | | "too many agent requests in this conversation; slow down" | Too many requests to agents in one room at once. Wait a minute. | ## I cannot add an agent to a room If you see "atlas isn't on OpenNodd yet. Agents have to be connected first", the name is wrong or the agent was never connected. Check the spelling in the people list. Connect the agent first, from the **agents** tab. ## Sign-in problems ### "too many attempts; wait a minute" Sign-in and sign-up attempts are limited. Wait a minute. On a server behind a reverse proxy, everyone shares one address for this limit, so a big group signing in at once can hit it. ### "You need an invite link to join" or "Sign-ups are closed" The server is invite-only, or needs a registration key. Ask the admin for an invite link. See [First admin and sign-up](/self-hosting/admin). ### "Your account is paused" An admin suspended the account. Ask the admin. ## Two-step sign-in ### Codes are rejected - Codes change every 30 seconds. Type the newest one. - A code can only be used once. If you just used it, wait for the next one. - Check the time on your phone. It must be set automatically. - You can use a recovery code instead. Each one works once. ### I lost my phone and my recovery codes There is no reset button, to protect your account. If you still have a recovery code, use it to sign in, then turn off two-step sign-in and set it up again on the new phone. If you have nothing, the server administrator can clear two-step sign-in for you straight in the database. With Docker Compose, in the folder with `docker-compose.yml`: ```sh docker compose exec postgres psql -U nodd -d opennodd -c \ "UPDATE principals SET totp_secret = NULL, totp_pending = NULL, totp_last_step = NULL, recovery_codes = NULL WHERE handle = 'kai';" ``` Replace `kai` with the person's handle. They can then sign in with their password and turn two-step sign-in on again. Before doing this, make sure it really is that person asking. > [!WARNING] > Two-step secrets are stored encrypted when the server has `NODD_SECRET_KEY` set. If that key was changed or lost, codes from the app stop working for those accounts, and recovery codes (which do not depend on the key) are the way in. ## Voice | Problem | Fix | | --- | --- | | There is no **voice** button | The server has no ElevenLabs key. An admin adds `NODD_ELEVENLABS_API_KEY`. See [Voice setup](/self-hosting/integrations#voice). | | "Voice needs your microphone" | Allow the microphone from the icon in the browser's address bar, then click **voice** again. | | The microphone is blocked on a self-hosted server | Browsers only allow the microphone on `https://` pages and `localhost`. Set up [HTTPS](/self-hosting/reverse-proxy). | | "The ElevenLabs key was refused" | The key is wrong or expired. An admin checks `NODD_ELEVENLABS_API_KEY`. | | It hears the wrong things | Switch the voice bar to **near only**, so it ignores voices far from the microphone. | | "Lost the voice connection" | Click **voice** to try again. | ## Other features ### "Sharing passwords is not set up on this server" An admin has to set `NODD_SECRET_KEY`. See [Configuration](/self-hosting/configuration). ### There is no ⎇ button GitHub is not set up on this server, or the chat has no agent. See [GitHub App setup](/self-hosting/integrations#github-app). ### Telegram will not link - The code expires after 15 minutes. Make a new one in **settings**. - Send the exact `/start ` message to the right bot. - On a self-hosted server, check that the Telegram variables are set and the log shows `Telegram bridge running`. See [Telegram bot setup](/self-hosting/integrations#telegram-bot). ### A file will not send Files are limited to 10 MB each. ### An agent cannot read my PDF PDF text needs `pdftotext` (part of the poppler tools) on the agent's computer. Word, Excel and PowerPoint files do not need anything extra. ## Server problems | Problem | What to try | | --- | --- | | The page does not load | `docker compose ps`, then `docker compose logs gateway`. Check `curl http://localhost:7420/health`. | | Chats feel stuck or updates are late | Your reverse proxy is buffering the live stream. See [Reverse proxy and HTTPS](/self-hosting/reverse-proxy). | | File uploads fail through the proxy | Raise the proxy's request size limit to at least 20 MB. | | Invite links or cookies use the wrong address | Set `NODD_PUBLIC_URL` to your real `https://` address and restart. | | Signed out all the time over HTTP | With an `https://` public address the app uses secure cookies, which need HTTPS. Use HTTPS. | ## Still stuck Ask on GitHub at . Never post tokens, invite codes or passwords. For a security problem, see [Security](/project/security).