Knowledge base / Under the hood

Troubleshooting

The problems people actually hit, and what is usually behind them.

Nothing is connecting

The line under your nym reads "Connected (n relays)". If n is zero or the app sits there doing nothing:

• Check the network. Nymchat needs outbound WebSocket connections. Corporate networks, some public Wi-Fi and some VPN configurations block them.
• Open Network Stats by tapping the connection line. It shows every relay with its own latency, which tells you whether one relay is slow or nothing is reachable at all.
• Turn on Low Data Mode under Settings › Data & Backup. Cutting to five core relays sometimes gets a connection through a flaky link that twenty will not.
• Reload. The web app reconnects on load; the mobile apps reconnect on resume.

Messages are missing

Almost always one of four things:

• Channel messages are ephemeral by design. Relays are expected to expire kind 20000 and 23333 events. History that has aged off the relays is gone; there is no archive to fetch it from.
• Different relays hold different things. Two people in the same channel on different relay sets genuinely see different messages. Turning off Low Data Mode widens the pool.
• A filter is hiding them. Check Blocked Keywords/Phrases and Blocked Users under Privacy & Security, and remember that flood protection mutes a rapid sender for fifteen minutes without telling you.
• The proof-of-work filter is set too high. Proof of Work Difficulty at 20 or 24 bits hides Nymchat's own messages, which is exactly what it says it will do. Set it to Disabled or 16.

For private messages specifically: if you have Accept Private Messages & Group Chat Requests on Friends only, messages from anyone not on your friends list are filtered out.

The mesh will not start

• The controls are not there at all — you are in Safari or Firefox, which do not implement Web Bluetooth. Nymchat hides the feature rather than offering something that cannot work. Use Chrome, Edge, Opera or Brave, or the mobile app.
• It is on but finds nobody — in a browser you must pick each device once through the browser's own chooser, using Add device. Nothing is discovered automatically, because a browser cannot advertise itself. See Turning it on.
• On mobile, nothing happens — check that Bluetooth is on and that the app has the Bluetooth permission. Android also needs Nearby Devices; some versions additionally want location services enabled for BLE scanning, which is an Android platform rule rather than something Nymchat asks for.
• Peers appear and vanish — that is Bluetooth range. The mesh extends reach by relaying through devices in between, so it needs devices in between.

The mesh panel has a live radio log. If something is wrong, it usually says so there.

Notifications do not arrive

• Permission. Notifications need the browser's or the system's permission, which is asked for once and then remembered — including a refusal.
• Sound. Notification Sound may be set to Silent under Settings › Messaging & Display.
• The web app must be open. A tab that is closed is not running, and nothing will notify you.
• On Android, turn on Stay Connected in Background. It runs a foreground service that keeps the relay connection open.
• On iOS, late notifications are expected. Nymchat has no push provider — there is no server holding your messages to push from — so a suspended app catches up in the background-refresh window iOS grants it, when iOS grants it. Opening the app always catches up immediately.

Locked out of an encrypted identity

If identity encryption is on and you cannot unlock — a forgotten password, a passkey on a lost device, a biometric that no longer matches — then the key is not recoverable. That is the point of it. There is no reset and no support route, because nobody holds a copy.

What you can do:

• If you backed up the nsec, log in with it again on a fresh session and re-enable encryption with a factor you will keep.
• If you did not, that identity is gone. Start a new one. Flair purchases can be restored from their recovery code; nothing else can.