Diagnosing Ngrok Custom Domain TLS Termination Failures

Problem Statement

After configuring a custom domain for an ngrok tunnel, you notice that the domain resolves but the browser refuses to load the page, or ngrok logs report a TLS handshake failure. The most common culprits are:

• DNS records not pointing to ngrok’s IP range or missing required CNAME/TXT entries.
• ngrok client reporting TLS handshake errors because the domain is unrecognized or the certificate is invalid.
• Authentication token missing, expired, or tied to a plan that doesn’t support custom domains.
• Client version outdated or not running, preventing domain registration.

Diagnostic Flow

Follow the table below to check each condition in order. After each check, apply the corresponding fix if needed. If the problem persists, move to the next row.

#	Check	What to Look For	Fix
1	DNS Resolution	Record points to ngrok IP or CNAME to *.ngrok.io	Add/Update CNAME or TXT record, then wait for propagation.
2	Ngrok Client Running	Client process active and listening on the tunnel port.	Start or restart the ngrok client.
3	Client Version	Version matches or exceeds latest release.	Upgrade with curl -s https://bin.equinox.io/c/4VmDzA7iaHb/ngrok-stable-linux-amd64.zip | unzip -p - ngrok-stable-linux-amd64/ngrok | tee /usr/local/bin/ngrok (Linux example).
4	Auth Token Validity	Token active, not expired, and linked to a paid plan supporting custom domains.	Run ngrok authtoken <token> to set a new token.
5	Ngrok Domain Registration	ngrok dashboard shows domain under “Custom Domains” with status “Active”.	Re‑register domain via ngrok custom-domains add <domain> or via dashboard.
6	TLS Handshake Logs	Logs contain “TLS handshake failed” or “Domain not recognized”.	Verify domain registration and DNS propagation; check ngrok logs for errors.

Step‑by‑Step Checks

1. Verify DNS Record

   Run the following command on a machine with internet access:

   dig +short <your.custom.domain>

   Expected output:

   • A CNAME pointing to *.ngrok.io (e.g., example.ngrok.io).
   • Or an A record within ngrok’s IP ranges (see ngrok IP ranges).

   If the output is empty or points elsewhere, update your DNS provider’s records.

2. Check Ngrok Client Status

   On the host running the tunnel, list running processes:

   ps aux | grep ngrok

   Or, if you use systemd:

   systemctl status ngrok

   Ensure the service is active. If not, start it with your tunnel command, e.g.:

   ngrok http 80 --host-header=localhost:80 --custom-domain <your.custom.domain>

3. Confirm Client Version

   Run:

   ngrok version

   Compare the output to the latest release. If it’s older, upgrade as shown in the table.

4. Validate Auth Token

   In the ngrok dashboard, locate your Auth Token. Then, on the client host:

   ngrok authtoken <your-token>

   Re‑run the tunnel command. If the token is expired or not linked to a plan that supports custom domains, you’ll see an error like “Custom domains not available on free plan”.

5. Inspect Domain Registration

   Navigate to the Custom Domains page. Your domain should appear with status “Active”. If it’s “Pending” or missing, re‑register:

   ngrok custom-domains add <your.custom.domain>

   After adding, the dashboard should update. If it remains pending, check the client logs for “Domain not recognized”.

6. Review TLS Handshake Logs

   Check the ngrok log file (default path: /var/log/ngrok.log or the console output). Search for:

   grep -i "tls handshake" /var/log/ngrok.log

   Typical error lines:

   • TLS handshake failed: unknown host
   • TLS handshake failed: certificate not yet valid

   These indicate the domain isn’t recognized by ngrok or the certificate is out of date. Re‑register the domain and ensure DNS propagation.

Concrete Example

Assume you set up api.myapp.local as a custom domain.

# DNS check
$ dig +short api.myapp.local
api.ngrok.io

# Client status
$ systemctl status ngrok
● ngrok.service - ngrok tunnel
   Loaded: loaded (/etc/systemd/system/ngrok.service; enabled)
   Active: active (running) since Mon 2026-10-16 10:12:00 UTC

# Client version
$ ngrok version
ngrok version 2.3.40

# Auth token
$ ngrok authtoken abcdef1234567890

# Register domain
$ ngrok custom-domains add api.myapp.local

# Verify in dashboard
# (Domain appears as Active)

If the browser still shows a TLS error, check the logs:

$ grep -i "tls handshake" /var/log/ngrok.log
2026-10-17T23:02:12Z ERROR tls handshake failed: unknown host

Solution: Ensure DNS propagation and re‑run ngrok custom-domains add. After propagation, the error disappears.

Limitations & Practical Checks

• ngrok’s IP ranges can change; avoid hard‑coding A records. Prefer CNAME to *.ngrok.io when possible.
• Free plans cannot register custom domains. Verify your plan in the dashboard.
• Certificates issued by ngrok expire after 90 days on paid plans. Automatic renewal occurs only for supported tiers.
• DNS propagation may take up to 48 h. Use dig +trace to follow the resolution path.

After performing all checks, you should see a secure HTTPS connection to your custom domain. If issues persist, contact ngrok support with the log excerpt and DNS query results.