Troubleshooting Remote Access
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.
- 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.
- 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.
- 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:
| Symptom | Where to look |
|---|---|
| The URL fails from cellular data too | The direct path itself is down. See Remote Access is stuck on a relayed connection. |
| A certificate or TLS warning in the browser | The 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, the Certificate as anything but Active, or the HTTPS listener as Stopped | The server side. See The Remote Access card says Relay only and Remote Access is stuck on a relayed connection. |
| Cardinal apps at home fall back to relayed connections | DNS 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.
The Remote Access card says Relay only
Relay only means your Media Server is connected to Cardinal Cloud but has no live certificate, so nothing can reach it directly. Apps still reach it, through the relay, which is metered against your subscription.
The card deliberately shows no public URL in this state. Your hostname exists, but a browser refuses a connection to a server that cannot prove it owns that name, so the address would fail if you dialled it. The URL appears on the card, and in the Direct Connection section of the drawer, as soon as a certificate is live — without reloading the page.
The Certificate readout in the drawer says which half of the wait you are in:
| Readout | What it means |
|---|---|
| Being issued | Cardinal is ordering the certificate. Normal for a minute or two after Remote Access is first enabled, or after your hostname changes. |
| Couldn't be issued | The order failed. The card carries the reason and when the server tries again. |
| Active | A certificate covers your hostname. Direct connections are possible, and the card shows the URL. |
Why an order fails
- The DNS challenge timed out. Cardinal proves ownership of your hostname by publishing a DNS record and waiting for the certificate authority to read it back. A slow propagation means the check runs out of time. This is the most common cause, and it usually succeeds on the next attempt with nothing done on your side.
- The order is in a cooldown. A failed order is not retried immediately. Cardinal backs off before trying that hostname again, which is the delay the card counts down.
- Your account has reached its certificate ceiling. Each account can obtain a limited number of new certificates per week. A server that has spent the allowance stays relayed until the window clears. See Limits on new certificates.
What to do
Nothing, in most cases. Cardinal retries on its own schedule, and the card shows when the next attempt is due — hover the countdown to read the exact time. Neither the failure nor the retry spends any of your weekly allowance.
Leave Remote Access switched on while you wait. Turning it off and on again does not re-order sooner, and a factory reset makes it worse: it changes your hostname, which means a new certificate against your weekly allowance rather than the retry you were already waiting on.
If the card is still relay-only a day later, contact support with your instance ID and the reason the card reported.
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:
- Your server has no certificate yet, or its order failed. A newly enabled server is relayed until its first certificate is issued, which normally takes under a minute. The card reports this as Relay only — see The Remote Access card says Relay only.
- You have reached the weekly certificate limit. See Limits on new certificates. The server stays relayed until the window clears, and the card reports it as Relay only.
- 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 Troubleshoot issues with DNS rebinding protection.
- Your browser has not been allowed onto the local network. Chrome asks before a Cardinal-hosted app may reach devices on your home network, and a declined or unanswered prompt leaves the app on the relay while you are at home. See Your browser asks to allow access to the local network.
- 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.
Your browser asks to allow access to the local network
When you open a Cardinal-hosted app such as music.cardinalapps.cloud at home, Chrome may show a prompt like "Allow music.cardinalapps.cloud to access devices on the local network". This is Chrome's local network access permission, introduced in Chrome 138: a page from the internet must be granted permission before it may talk to addresses on your home network. Every app origin asks once, and the answer is remembered.
Choose Allow. The app then connects to your Media Server directly over your home network, which is the fastest path and keeps your traffic off the relay. While the prompt is open, the app waits for your answer rather than giving up on the local connection.
If you declined the prompt, or closed it, the app stays on the relay at home. To change your answer, open the site information panel from the icon at the left of the address bar, find Local network access, and set it to Allow, then reload the app.
Firefox and Safari do not show this prompt today. If a browser without the prompt still cannot reach your server at home, the cause is usually DNS rebinding protection on your router.
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 as1.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:
- 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.
- 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.
- 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?