Troubleshooting a connection

Connection failures can begin on your Mac, somewhere along the network path, or at the IRC server. Start with the error shown in the server console so that you can change one thing at a time.

Check the basics

1. Confirm the server address, port and TLS settings using the network's own connection information.
2. Check that your Mac has a working internet connection, including any required captive-portal sign-in.
3. Look for a server notice about authentication, bans, connection limits or maintenance.
4. If you use a proxy, VPN, firewall or bouncer, check its configuration and connection separately.

A working web browser does not prove that an IRC port is reachable. Equally, another client staying connected does not establish that Textual's connection takes the same route or uses the same settings.

Certificate and authentication errors

Use the certificate troubleshooting guide for TLS errors and the authentication guide for SASL or NickServ errors. Keep certificate verification enabled while investigating.

Timeouts and keepalives

Textual includes settings to periodically PING a connection, disconnect when a response does not arrive, and react to network reachability changes. These help detect a connection that has stopped working and allow a reconnect.

Look under Server Properties → Advanced for the network socket settings in your build. Keep the normal detection behavior unless you have evidence that a particular setting is responsible; simply suppressing disconnects may leave you looking at a connection that is already dead.

IPv4, IPv6, and socket settings

The connection-type setting can help isolate an IPv4- or IPv6-specific problem. Test one change at a time, since support and routing depend on your network and provider. Neither protocol is inherently the explanation for every timeout.

The original guide also describes a Prefer modern sockets hidden preference. Treat that as version-specific troubleshooting rather than a routine setup step, and mention any change to it when requesting support.

Sleep and changing networks

Moving between Wi-Fi networks, suspending a VPN, or putting the Mac to sleep can interrupt a connection. A bouncer can remain connected independently of the Mac, but it cannot repair a broken connection between the Mac and itself.

If the problem persists, send us the exact error, relevant settings with secrets removed, and whether the failure happens on more than one network.