Troubleshooting

• Check host and port. TLS servers typically use port 6697; plaintext servers use 6667.
• Toggle TLS. Try disabling it temporarily to confirm whether it's a TLS issue.
• Try a different server address. Most large networks have regional round-robin DNS (e.g. irc.libera.chat vs irc.au.libera.chat).
• Check the server buffer. Error messages appear there (e.g. You are banned, Server is full).
• Check your internet connection. Confirm the IRC port isn't blocked by a firewall or ISP.

Error codes 904, 905, 906, or 907 in the server buffer indicate a SASL failure.

• Check your authcid. This is your NickServ account name — usually your registered nick.
• Check your password. Passwords are case-sensitive. Temporarily disable SASL and use /ns IDENTIFY password to verify manually.
• Try PLAIN instead of SCRAM-SHA-256. Not all servers support SCRAM.
• EXTERNAL / CertFP: Ensure you've registered your cert fingerprint with NickServ (/ns CERT ADD) and the certificate is imported in network settings.
• Disable SASL temporarily. The connection still succeeds — you just won't be identified.

• TOFU fingerprint mismatch: The server's certificate has changed since you first pinned it. If the change is legitimate (cert renewal), clear the stored fingerprint by editing the network and saving (this resets the pin), then reconnect with Allow invalid certificates on to re-learn. If you don't recognise the change, treat it as a possible MITM attempt and verify with the server admin before reconnecting.
• Self-signed certificate: Turn on Allow invalid certificates in network settings. On first connect HexDroid will learn the fingerprint and pin it automatically. From then on every subsequent connection is verified against the pin, refusing silent swaps.
• Fingerprint copy-paste: If you want to pre-seed a fingerprint by hand (e.g. pasted from your bouncer's admin page), HexDroid accepts the standard SHA-256 colon-separated hex format and also tolerates uppercase, missing colons, or whitespace.
• Expired certificate: TOFU verifies the fingerprint regardless of expiry. If the cert is expired but the fingerprint matches, the connection still succeeds — HexDroid trusts what you pinned. Contact the server admin if you want them to renew.
• Hostname mismatch: With Allow invalid certificates off, Android's default trust chain enforces hostname matching. Try connecting to the canonical hostname shown in the certificate.
• TLS version mismatch: Very old servers may only support TLS 1.0/1.1, which Android 10+ rejects. You may need to disable TLS entirely for that server.

• Android 13+ permission: Go to Android Settings > Apps > HexDroid > Notifications and confirm notifications are enabled.
• In-app toggle: Make sure both Notifications enabled and Notify on highlights are on in HexDroid's Settings screen.
• Do Not Disturb: DND or Focus mode silences all notifications.
• Battery optimisation: If HexDroid is killed in the background, notifications won't arrive until it reconnects. See Always connected issues below.
• Highlight detection: By default, only your nickname triggers a highlight. Add extra keywords in Settings > Extra highlight words.

Some manufacturers aggressively kill background apps to save battery. If HexDroid disconnects shortly after you close it:

• Disable battery optimisation for HexDroid: Android Settings > Apps > HexDroid > Battery > select Unrestricted.
• Check the persistent notification: When "Keep alive in background" is on, a notification must be visible. If it disappears, the foreground service was killed.
• Lock the app in Recents: Long-press HexDroid in Recent Apps and tap a lock icon (if available).

Manufacturer-specific steps

DCC requires a direct network connection between you and the other user, which is often blocked by NAT or firewalls.

• DCC is off by default. Enable in Settings > DCC enabled.
• NAT / home router: Incoming DCC requires port forwarding. Set an incoming port range (e.g. 5000–5010) in Settings and forward those ports from your router.
• Passive / Reverse DCC: If active DCC fails, switch to Passive mode. The receiving side initiates the connection, bypassing NAT on your end.
• Mobile data (CGNAT): Most mobile networks use Carrier-grade NAT — incoming connections are impossible. Use Wi-Fi, or ensure the other party accepts connections.
• VPN: Active VPNs often interfere with DCC's direct connection model. Try disabling the VPN for transfers.

• Wrong encoding: The network may use a non-UTF-8 encoding. In network settings > Character encoding, select the correct one:
  • windows-1251 — Russian / CIS networks
  • KOI8-R — older Russian systems
  • ISO-8859-1 — Western European
  • ISO-8859-2 — Central/Eastern European
• Auto-detect: Revert to Auto if you've overridden it — HexDroid auto-detects encoding per message.

• Alternate nick: Set an alternate nickname in network settings. HexDroid uses it automatically if your primary nick is taken.
• Ghost your old session: Use /ns GHOST YourNick password then /nick YourNick, or add these as post-connect commands with a 2–3 second delay.
• Note: SASL only handles initial authentication, not nick recovery. NickServ GHOST and REGAIN work independently.

HexDroid shows a specific error message for join failures.

• Invite-only (+i): You need to be invited. Ask a channel operator to /invite YourNick #channel.
• Key-protected (+k): Use /join #channel key, or add the key to the auto-join entry in network settings.
• Full channel (+l): The channel has reached its user limit. Try again later.
• You are banned (+b): Your hostmask matches a ban entry. Contact a channel operator.
• Registered users only (+r): Configure SASL, or use a post-connect /ns IDENTIFY command.

• Logging is off by default. Enable in Settings > Logging enabled. Without logging, /find only searches the current in-memory scrollback.
• Custom log folder: If you selected a custom folder via SAF and storage permission was later revoked, logging fails silently. Reset the folder to the default in Settings.
• Retention period: Logs older than the configured retention period (default 14 days) are automatically deleted.