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 (v1.5.5+): The server's certificate fingerprint has changed since you first connected. If the change is legitimate (e.g. the admin renewed the cert), go to Networks > TLS > Reset pinned certificate, then reconnect to learn the new fingerprint.
• Self-signed certificate: On first connect HexDroid's TOFU system will learn the fingerprint automatically — no configuration needed. If you see an error anyway, check the server hostname matches what you entered.
• Expired certificate: TOFU will still verify the fingerprint but report an expiry warning. Contact the server admin to renew the cert.
• Hostname mismatch: 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.