Table of Contents

Troubleshooting

If you're having trouble establishing a chat with your partner, the first thing to check is whether you're using the same password. Note that if one partner's password setting is blank, then the other partner's password setting must be blank too.

Besides mismatched passwords, most of the issues with chats involve the "Automatically listen for partner" setting. See Settings for more information about that setting. In technical terms, each chat connection has a client and a server: the server listens for connections, and the client connects to the listening server. When you select "Chat" in the toolbar, Underpass becomes a client. When you select the "Automatically listen for partner" setting, Underpass becomes a server. The client side is usually not a problem, because your Mac acts as a client all the time, for example when you load a web site in your browser or check and send email. Configuring a server properly is more complex, so the following sections apply mostly to the "Automatically listen for partner" setting.

Firewalls

A firewall is a security system that blocks certain network traffic. In most cases a firewall should not interfere with Underpass, but if there is an overly strict or poorly configured firewall on your network, then it's possible that the firewall could block Underpass chats.

Your Mac has a built-in firewall. The firewall is off by default, in which case it poses no problem. Underpass can also operate with the firewall on, as long as the firewall is properly configured. If you select "Automatically listen for partner" in Underpass, then you must not block incoming connections with the firewall. Underpass needs to receive an incoming connection in order for your partner to start a chat with your Mac. If the firewall indicator is yellow, with a warning icon below, then you need to change the configuration.

System Preferences, Firewall

Firewall Options

To allow Underpass to receive incoming connections, make sure that "Block all incoming connections" is not selected. The firewall indicator will then be green:

Firewall Options

System Preferences, Firewall

When you run Underpass, the system shows an alert that asks whether you want to allow the application Underpass to accept incoming network connections. Make sure to select "Allow". Do not select "Deny", otherwise the firewall will block Underpass.

Do you want the application Underpass app to accept incoming connections?

If you already selected "Deny" in the alert, then you will need to manually edit the firewall rules. If Underpass is set to "Block incoming connections", change it to "Allow incoming connections".

Allow incoming connections

On macOS 10.12 Sierra there is a firewall setting "Automatically allow built-in software to receive incoming connections". You may want to select this setting, to make sure that crucial system functions are not blocked, such as Bonjour network service discovery, which is used by LAN chats in Underpass.

Automatically allow built-in software to receive incoming connections

There are third-party firewalls that you can install on your Mac, such as Little Snitch, Norton, or Symantec. If you've installed one of these, and you're having trouble with Underpass chats, then please consult your firewall product manual or contact the firewall vendor for support in configuring your firewall.

Internet Ports

In a home or an office, your Mac is typically not connected directly to the internet. Instead, your Mac is behind a router. A router allows multiple computers to share a single internet connection. A router also protects your computers by blocking unexpected traffic from the internet from reaching your computers; in this way, the router is a kind of firewall, as discussed above. Although this protection is usually desirable, it could prevent you from receiving Underpass chats behind a router. Therefore, if your Mac is behind a router, then your router must be configured to allow Underpass chats from the internet.

When you select "Automatically listen for partner", Underpass attempts to perform port mapping on your router. Port mapping allows traffic coming from the internet destined for a certain port to reach that port on your Mac. Underpass supports port mapping for a number of models of router, including Apple's AirPort Extreme and AirPort Express base stations. If the port mapping succeeds, Underpass shows this in the settings popover.

Router port mapping succeeded

If there is a problem with port mapping, Underpass also shows it.

Router port mapping unavailable

Not all router models support automatic port mapping, so you may need to check your router documentation or contact your router vendor to learn how to set up port mapping manually. Also, it's possible to disable port mapping on some routers, so make sure port mapping is enabled. For Apple's AirPort base stations, you can check the port mapping status with the AirPort Utility app.

Enable NAT Port Mapping Protocol

Whether Underpass configures port mapping automatically or you configure it manually, you can test whether port mapping is functioning correctly by using the "Test my listening port" link in the settings popover. This link opens a third party web site in your default web browser. The web site is a service that will attempt to contact your Mac from the internet on your selected port. If all is well, then the Underpass port should be open. (It's ok to see "Unknown Protocol" and "Unknown Application", because the web site doesn't know anything about Underpass.)

Test my listening port

Multiple chat windows cannot simultaneously listen for a partner on the same port. If you try, you'll see an error like this:

Port is already in use.

When you see that error, please choose a different port for your chat. Each chat that is listening must use a different port. You may also see that error if some other application on your Mac is already listening for a connection on that port. The use of a port is usually exclusive, which is why your computer has many ports available.

Internet Addresses

When you select "Automatically listen for partner", Underpass attempts to automatically detect your IPv4 address. If your IPv4 address is detected, then it is displayed in the settings popover.

My IPv4 address

This works with many but not all models of router. If Underpass cannot detect your IPv4 address, and you don't already know it, then you can use the "What is my IP address" link in the settings popover to discover it. This link opens a third party web site in your default web browser. The web site is a service that will show your IP address.

What is my IP address?

Your IP address may or may not change over time. Thankfully, many Internet Service Providers (ISP) give you the same IP address all of the time. Some ISPs allow you to specially request a static IP address, perhaps with an additional service charge. If for some reason your ISP changes your IP address, your partners will have to change the "Partner's address" in their settings in order to chat with you again. Underpass will warn you if it detects that your IP address has changed. If your ISP changes your IP address, and you can't obtain a static IP address from your ISP, one solution is to sign up for a third party Dynamic Domain Name Service (DDNS). Some of these services are free, others are paid. Dynamic DNS services give you a static domain name through which your Mac can always be reached, i.e., mydomain.com. Your chat partners would enter your domain name in the "Partner's address" instead of entering your IP address. The Dynamic DNS service updates the DNS entry for your domain name automatically to point to your new IP address whenever your IP address changes.

Bonjour

LAN chats in Underpass use the Bonjour network service discovery protocol to allow chat partners to find each other on the network. Bonjour is built into the Mac operating system and runs by default. In most cases, Bonjour should just work, but there are a few circumstances in which it may not work:

  1. It is possible to disable Bonjour on a Mac through some advanced command-line configuration.

    You would probably know if you had done this to your own Mac. It would be unusual but not inconceivable that Bonjour would be deliberately disabled by the network administrator on Macs in a school or office.

  2. A firewall could block Bonjour services.

    Please see the Firewalls section above for more information on how to properly configure firewalls.

  3. Your router could block Bonjour services.

    Check your router to make sure that Bonjour traffic is allowed. Bonjour uses port 5353, so this port must not be blocked.

  4. The LAN itself could block Bonjour services.

    This may happen on a network that you do not control, such as in an office, coffee shop, or school. In that situation, if automatic discovery of chat partners does not appear to be working, ask the local network administrator about Bonjour support.

Note that your own computer name will not appear in your "Partner's computer" popup menu. Underpass automatically filters it out of the list, to avoid confusion and selecting the wrong name.

Bonjour Settings

Next: Contact support

Table of Contents