Connection Issues

Symptom

Your tunnel is not working — the service is not reachable from the internet. Clients see connection timeouts, refused connections, or DNS errors when trying to reach your airdress name.

Quick checks

Run these three commands first. They cover the most common failure points and tell you exactly where to look next.

# 1. Is the operator running and healthy?
airdress-operator health

# 2. Is your name resolving to the relay VIP?
dig myname.a.airdr.es @185.43.32.1

# 3. What does the client actually see?
curl -v https://myname.a.airdr.es

Tip

Replace myname with your actual airdress name throughout this page.

Possible causes

Ranked by likelihood:

1. Operator not running
2. Local service not listening on the target port
3. DNS not resolving (NXDOMAIN or SERVFAIL)
4. Firewall blocking WireGuard (UDP 51820)
5. Relay PoP unreachable
6. TLS certificate error

Diagnosis and fixes

Operator not running

The operator process must be running for the tunnel to stay up.

Diagnose:

systemd

systemctl status airdress-operator

Healthy output:

● airdress-operator.service - Airdress Operator
     Active: active (running) since ...

Failure output:

● airdress-operator.service - Airdress Operator
     Active: inactive (dead)

Manual

airdress-operator health

Healthy output:

status: healthy
tunnel: connected
uptime: 3h 42m

If the command fails with “connection refused”, the operator is not running.

Fix:

systemd

sudo systemctl start airdress-operator
sudo systemctl enable airdress-operator   # persist across reboots

Manual

airdress-operator serve

If the operator exits immediately, check its logs for configuration errors:

journalctl -u airdress-operator --no-pager -n 50

Tip

Run airdress-operator config --check to validate your configuration file before starting the operator.

---

Local service not listening

The operator reverse-proxies incoming traffic to a local port. If nothing is listening on that port, clients see a 502 Bad Gateway.

Diagnose:

# Check if your service is listening (replace 8080 with your target port)
ss -tlnp | grep 8080

Healthy output:

LISTEN  0  128  127.0.0.1:8080  0.0.0.0:*  users:(("myapp",pid=1234,fd=3))

No output means nothing is listening on that port.

Alternative check:

lsof -i :8080

Fix:

Start your local service so it listens on the configured port. The operator forwards to 127.0.0.1:8080 by default — make sure your service binds to that address and port.

# Verify the operator can reach it locally
curl -s http://127.0.0.1:8080/

---

DNS not resolving

If dig returns NXDOMAIN or SERVFAIL, the name is not resolvable and clients cannot find your service.

Diagnose:

1. Query the authoritative DNS PoPs directly:

   dig +short myname.a.airdr.es @185.43.32.1

   Expected: 185.43.32.11 (the relay VIP).

   NXDOMAIN means the name does not exist in the DNS PoPs.

2. Compare with a public resolver:

   dig +short myname.a.airdr.es @8.8.8.8

   If the authoritative server returns the correct answer but Google DNS does not, the record exists but has not propagated yet.

3. Check the operator’s view:

   airdress-operator dns list

Fix:

• If the name was just claimed, wait 2-5 minutes for DNS propagation. The hub reconciler syncs records to DNS PoPs on a 60-second tick.

• If the name does not appear in airdress-operator dns list, verify it was claimed successfully in the hub.

• Check your operator status to confirm the name is bound:

  airdress-operator status

---

Firewall blocking WireGuard

The operator establishes a WireGuard tunnel to the relay on UDP port 51820. If your firewall blocks outbound UDP 51820, the tunnel cannot connect.

Diagnose:

# Check for rules that might block UDP 51820
sudo iptables -L -n | grep 51820

If you see a DROP or REJECT rule for port 51820, that is the problem.

You can also test connectivity to the relay:

# Check if WireGuard handshake succeeds
airdress-operator status

Look for tunnel: disconnected or tunnel: handshake timeout.

Fix:

ufw

sudo ufw allow 51820/udp

iptables

sudo iptables -A INPUT -p udp --dport 51820 -j ACCEPT
sudo iptables -A OUTPUT -p udp --dport 51820 -j ACCEPT

firewalld

sudo firewall-cmd --add-port=51820/udp --permanent
sudo firewall-cmd --reload

Caution

Some corporate networks and cloud providers block UDP traffic entirely. If you are behind a strict corporate firewall, you may need to ask your network administrator to allow outbound UDP 51820.

---

Relay PoP unreachable

If the relay infrastructure itself is down, no tunnels will work regardless of your local configuration.

Diagnose:

curl -s https://relay.airdress.co/health

Healthy output:

{"status":"ok"}

If the request times out or returns an error, the relay may be experiencing an outage.

Fix:

This is an infrastructure issue on the Airdress side. Check the status page for ongoing incidents:

Airdress Status Check for active incidents and scheduled maintenance.

---

TLS certificate error

If clients see certificate warnings or errors, the TLS certificate for your airdress name may not be issued yet or may have expired.

Diagnose:

openssl s_client -connect myname.a.airdr.es:443 -servername myname.a.airdr.es </dev/null 2>/dev/null | openssl x509 -noout -dates -subject

Healthy output:

subject=CN = myname.a.airdr.es
notBefore=May  1 00:00:00 2026 GMT
notAfter=Jul 30 23:59:59 2026 GMT

If the certificate subject does not match your name, or the dates show it has expired, that is the problem.

Fix:

• Certificates are provisioned automatically. If the name was just claimed, wait a few minutes for the certificate to be issued.

• If the certificate has expired, restart the operator — it will attempt renewal on startup:

  sudo systemctl restart airdress-operator

• Check operator logs for certificate-related errors:

  journalctl -u airdress-operator --no-pager | grep -i cert

Still stuck?

If none of the above resolves your issue, gather diagnostic output and reach out:

# Collect a diagnostic bundle
airdress-operator health
airdress-operator status
airdress-operator config --check

Open a GitHub issue Include the diagnostic output above when filing an issue.

You can also email support@airdress.co with the diagnostic output attached.