Skip to main content

Troubleshooting Remote Access

Claude
Authored by Claude · Last updated AI generated documentation written by reading the source code
cloud servicesclosed beta

This page collects the problems that come up with Remote Access, what causes each one, and how to confirm and fix it.

The URL works away from home but not on my own network​

A Remote Access URL is a public address. It is designed to be dialled from outside your home, and on most networks it works from inside as well. On some networks it does not: the URL that loads instantly on cellular data times out from the couch.

This is almost always the router, not Cardinal, and not your Media Server.

Why the public URL can fail at home​

Your Media Server's direct URL looks like this:

https://abc123.connect.cardinalapps.host:24900

Fig. 1 — a direct Remote Access URL. The port is the one your deployment publishes; 24900 is the one the Quick Start uses.

That hostname always resolves to your network's public (WAN) IP address — the single address your router presents to the internet. It never resolves to your Media Server's address on your local network. Every request to that URL therefore has to pass through the router, which forwards it to the Media Server inside.

From outside your home, that is a straight line:

phone on cellular ──▶ 198.51.100.10 (your WAN IP) ──▶ router ──▶ 192.168.1.40:24900

Fig. 2 — reaching the server from another network

From inside your home, the same request has to make a U-turn. It leaves a device on your network, travels out to the router's WAN address, and has to be sent straight back into the network it just came from:

laptop on your LAN ──┐
                     ▼
              198.51.100.10 (your WAN IP)
                     │
                  router ─────┐
                     ▲        │ the U-turn
                     └────────┘
                     │
                     └──▶ 192.168.1.40:24900

Fig. 3 — reaching the server from your own network

Routers call that U-turn NAT loopback. The same feature is also sold as NAT reflection and hairpin NAT; the three names mean the same thing. Support for it varies:

  • Most modern routers support it, and the public URL works from everywhere without any configuration.
  • Some routers do not implement it at all. ISP-supplied gateways are the usual offenders, and often have no setting to turn it on.
  • Some implement it for other devices on the network, but fail the degenerate case where the machine hosting the Media Server dials its own WAN mapping. On those routers the URL works from every device at home except the server itself.

Your hostname, your certificate, and your port forward are all fine in this situation. The packets simply never complete the turn.

Confirming it is NAT loopback and not an outage​

The tell is that the URL works from everywhere except the network your Media Server is on.

  1. Open the direct URL on a phone with Wi-Fi turned off, over cellular data. If it loads, then your Media Server, its port forward, its certificate and Remote Access itself are all healthy.
  2. Open the same URL on a device connected to your home network. A request that hangs and eventually times out, with no certificate warning and no error page from the server, is the signature of missing NAT loopback.
  3. If step 2 succeeds on other devices but fails only on the machine running the Media Server, you have the partial case described above. The fix is the same.

Your direct URL is in the Admin Dashboard, under Cloud Services → the Remote Access card → Configure → the Direct Connection section, where it can be copied.

These symptoms are not NAT loopback:

SymptomWhere to look
The URL fails from cellular data tooThe direct path itself is down. See Remote Access is stuck on a relayed connection.
A certificate or TLS warning in the browserThe connection is reaching the server. Check the hostname in the URL against the one in the Direct Connection section.
The drawer reports Connection as anything but Active, or the HTTPS listener as StoppedThe server side. See Remote Access is stuck on a relayed connection.
Cardinal apps at home fall back to relayed connectionsDNS rebinding protection, not loopback. See Troubleshoot issues with DNS rebinding protection.

Fixes​

Enable NAT loopback on your router​

This is the real fix, and it makes one URL work from every network, which is the whole point of having a public address.

Look through your router's administration pages for a setting named NAT loopback, NAT reflection, or hairpin NAT. It is rarely on the front page. Common locations are under NAT, firewall, WAN, or advanced networking settings, and on some firmware it is a per-port-forward checkbox rather than a global switch. pfSense and OPNsense expose it under their NAT settings; OpenWrt and most enthusiast firmware support it by default.

ISP-supplied gateways are the common dead end. Many hide the setting, ship it disabled with no way to enable it, or lack the feature entirely. If yours does, put the gateway in bridge mode behind a router of your own, or use one of the two options below.

Use the local address at home​

Nothing on your own network needs to go out to the internet and back. On your home network, reach the Media Server at its local address and port instead:

http://192.168.1.40:24900/admin

Fig. 4 — a local address

The Media Server prints its own local address when it starts. Run docker compose logs -f and look for the Welcome box, which lists the address for the Admin Dashboard and each app.

This costs you nothing but a second bookmark. Cardinal's own apps already do the equivalent on their own: they prefer a local connection whenever they are on the same network as the server, so their playback at home is unaffected by NAT loopback.

Pin the hostname to the local address with a hosts file​

Advanced. This keeps the exact same URL, the same certificate, and the same bookmark working at home, which the previous option does not. It is useful when something has the Remote Access URL baked into it and cannot be pointed at a local address.

A hosts file entry overrides DNS on one device, so the Remote Access hostname resolves to the Media Server's local address instead of your WAN address. The request then goes straight across your network, never touches the router's NAT, and never needs loopback. The certificate stays valid because the URL — and therefore the name the certificate is checked against — has not changed, and the Media Server answers TLS on the same port it serves everything else on, so the request lands on the same listener that answers it from the internet.

On macOS and Linux, add a line to /etc/hosts:

192.168.1.40  abc123.connect.cardinalapps.host

Fig. 5 — a hosts file entry, using your server's local IP address and your own hostname

On Windows, the file is at C:\Windows\System32\drivers\etc\hosts and must be edited as an Administrator. The line is identical.

Keep the following in mind:

  • The entry applies to one device. To do this for the whole network, set the same override in a local DNS server such as Pi-hole, AdGuard Home, dnsmasq, or Unbound.
  • A hosts file cannot contain a port. Keep the port in the URL you visit exactly as it appears in the Direct Connection section, and note that this only works when your router forwards that port to the same port on the Media Server. If the two differ, use the local address instead.
  • A laptop that leaves the house takes the entry with it, and the hostname will keep resolving to a local address that is no longer reachable. Remove the entry from devices that travel, or use a local DNS server, which only applies while the device is on your network.
  • If your hostname changes, the entry stops matching and has to be updated. See Actions that change your hostname.

Devices at home do not need Remote Access​

Remote Access exists to reach your Media Server from networks it is not on. On your own network the server was always directly reachable, and it stays that way whether Remote Access is on, off, or waiting on a certificate.

Cardinal's apps behave accordingly. When they are on the same network as the Media Server they take a local connection first and only fall back to the internet and then the relay, so a router with no NAT loopback does not affect streaming at home. What it affects is manually opening the public URL from inside the house: bookmarks, links you sent yourself, and anything you point at the URL by hand.

Remote Access is stuck on a relayed connection​

A relayed connection always works, but it is slower than a direct one and routes your traffic through Cardinal's servers. If your apps never progress past the relay, work through these causes in order:

  1. Your server has no certificate yet. A newly enabled server is relayed until its first certificate is issued, which normally takes under a minute. Check the Remote Access section of your Media Server's settings for its current status.
  2. You have reached the weekly certificate limit. See Limits on new certificates. The server stays relayed until the window clears.
  3. Local connections are blocked by DNS rebinding protection. This affects only the local (LAN) candidates, so streams from outside your home still work while playback at home is relayed. See the next section.
  4. Inbound connections are blocked. Direct internet connections require your Media Server's port to be reachable from outside your network. If your router does not support UPnP or NAT-PMP, or has it disabled, the internet candidate fails and the relay is used instead.

If none of these apply and the server remains relayed, contact support rather than factory resetting the server — a reset changes your hostname and consumes part of your weekly certificate allowance without addressing the cause.

Troubleshoot issues with DNS rebinding protection​

The local (LAN) candidates are public DNS names that intentionally resolve to private IP addresses. For example, if your Media Server's LAN address is 192.168.1.40, apps on the same network connect to a hostname like:

192-168-1-40.abc123.connect.cardinalapps.host  →  192.168.1.40

Some routers and DNS resolvers ship with DNS rebinding protection, a security feature that blocks public DNS names from resolving to private addresses. Rebinding protection cannot tell this legitimate answer apart from an attack, so it silently discards it.

Symptoms​

  • Apps on the same network as the Media Server fall back to relayed or internet connections instead of connecting locally (slower streams, unnecessary internet traffic).
  • Local playback fails entirely while Remote Access works fine when you are away from home.
  • nslookup 192-168-1-40.abc123.connect.cardinalapps.host (using your own hostname) returns no answer on your network, but returns the private address on another network or against a public resolver such as 1.1.1.1.

Allow connect.cardinalapps.host in your resolver​

The fix is to whitelist connect.cardinalapps.host in whichever device answers DNS on your network — usually your router, or a local DNS server such as Pi-hole. This creates a narrow exception: only names under connect.cardinalapps.host may resolve to private addresses, and rebinding protection stays active for everything else.

dnsmasq (OpenWrt, Pi-hole, many routers)​

Add to the dnsmasq configuration:

rebind-domain-ok=/connect.cardinalapps.host/

On OpenWrt this can be set in /etc/config/dhcp:

config dnsmasq
    list rebind_domain 'connect.cardinalapps.host'

Unbound (pfSense, OPNsense)​

Add to the custom Unbound options (pfSense: Services → DNS Resolver → Custom options; OPNsense: Services → Unbound DNS → Custom options):

server:
    private-domain: "connect.cardinalapps.host"

AVM FRITZ!Box​

Under Home Network → Network → Network Settings → DNS Rebind Protection, add connect.cardinalapps.host to the host name exceptions.

Other routers​

Look for a setting named "DNS rebind protection", "rebind domain exceptions", or similar, and add connect.cardinalapps.host as an exception. If the setting cannot be scoped to a domain, an alternative is to use a local DNS server (such as Pi-hole or AdGuard Home) that supports per-domain exceptions, or to configure your devices to use a public resolver.

My custom address is stuck setting up, or could not be set up​

A custom address starts working when the certificate covering it is issued, which normally takes a minute or two. Until then the Direct Connection section reports it as still being set up, and the name does not resolve.

Your instance ID address is unaffected the whole time. It keeps its own certificate, apps keep connecting through it, and nothing about the claim puts your server on the relay. A custom address that never comes up costs you the name, not the connection.

Still setting up after several minutes​

Certificate issuance is the slow part, and it is subject to the same weekly allowance as everything else. If the name has not gone live:

  1. Check your certificate allowance. Claiming a name buys a certificate. If the account has spent its allowance for the week, the name stays claimed but the certificate waits for the window to clear. See Limits on new certificates.
  2. Confirm the server is online. A certificate is delivered to a running Media Server. A server that is offline, mid-upgrade, or between restarts receives it on its next connection.
  3. Reopen the drawer to refresh the status, rather than waiting on an open one to change by itself.

The name is yours while this is happening. There is nothing to re-claim, and claiming the same name again does not restart anything.

The address could not be set up​

If the section reports the setup as failed, the certificate order did not complete. The name is still reserved for your server, and the failure does not spend any of your weekly certificate allowance — issuance is Cardinal's side of the connection, so a failure there is not charged to you.

Cardinal retries on its own. Failed orders are picked up by a daily certificate sweep, and reconnecting your Media Server triggers a retry too once a short back-off has passed, so a name that failed in the afternoon is often live the next morning without any intervention.

Do not release the name and claim it again as a first move. That spends a replacement against the rate limits and puts the released name into its 90-day lock, where only your own account can take it back. If the status is still failed a day later, contact support with your instance ID and the name you claimed.

The name I want is unavailable​

The field reports a single unavailable for every name it will not take. That covers names another server already holds, names in the 90-day lock after being released, names reserved by Cardinal, and names that collide with Cardinal's own infrastructure. The app does not distinguish between them, and there is no way to be notified when a name frees up.

Names that break the format rules — shorter than 3 characters, longer than 30, anything outside lowercase letters, digits and hyphens, or a leading or trailing hyphen — are refused as invalid rather than unavailable. See Choosing a name.

One case is worth knowing about: a name you released is available to your own account for the whole 90 days, so if you released a name and want it back, try it. It will be refused only if it has since been claimed by someone else after the window ended.

Was this article helpful?