Domains, DNS & SSL

A working custom domain needs DNS that reaches the server (or your own proxy), a route to the right app, and a certificate on the server or at your proxy. This page explains the failure messages and which part to check.

If you haven't added a domain yet, start with the custom domains guide; this page is for when something is already stuck. The Domains page is the quickest overview: it shows each domain's live DNS answer, certificate state and the reason for the last failure.

Verification keeps failing

What it means. Let's Encrypt couldn't confirm the name through this server. Synq reads certbot's output and puts the real cause first. The common ones:

How to fix, step by step

1. Check the hostname points at your server: dig A app.example.com should return the server's public IP. A free subdomain (<slug>.<domain>) relies on the wildcard record *.<domain> instead.
2. Check for an AAAA record: dig AAAA app.example.com. Let's Encrypt tries IPv6 first, so an AAAA pointing elsewhere breaks issuance. Point it at this server or delete it.
3. Make sure port 80 reaches the server from the internet (firewall, security group, NAT).
4. Delete any old, conflicting record for the same name.
5. Press Verify again. The Domain DNS verification job also retries on its own, less often after each failure (see Automatic retries).

After a failed check, Synq also looks up the hostname's DNS. If it has no record, or answers with an address that isn't the server serving the project, an Issue titled "app.example.com is not pointing at this server" opens on the Monitoring page with the addresses found, the expected server IP and the record to add. It updates on each automatic re-check and resolves itself once DNS points here and the certificate is issued. The lookup only explains a failure; it never blocks verification, so a CDN in front of a working domain is unaffected.

DNS hasn't propagated yet

What it means. DNS isn't instant. After you save a record it has to spread across the internet's caches. Usually that takes minutes; occasionally hours (the panel warns it can take up to 48 hours).

How to fix

1. Double-check the Host field for typos and remove leftover records for the same name.
2. Use Check DNS on the Domains page to see what public DNS answers now (it asks Google's public resolver). If your own dig doesn't show the new value yet either, it's a propagation delay.
3. Wait. The Domain DNS verification job (on by default) first retries a pending domain once it is 10 minutes old, then backs off (15 minutes up to every 6 hours), and issues the certificate once DNS is right. It only retries domains of projects with a live deployment. Pressing Verify is only the faster retry.

Verified, but no certificate yet

What it means. Issuance is still running, its result hasn't been read yet, or the first attempt failed.

How to fix

1. Give it a moment, then open the domain's ⋯ menu and click Recheck SSL (Recheck certificate on the Domains page). It only reads the certificate on the server, so it spends no Let's Encrypt quota, and flips the state to Active once the certificate is there.
2. If it says no valid certificate was found yet, wait a little longer and recheck.
3. The scheduled domain job retries incomplete issuance. For an immediate retry, click Renew SSL; the real failure reason (DNS, blocked ports, rate limit, CA outage) appears there.

A certificate didn't renew

What it means. The daily SSL certificate renewal job (ssl:renew) renews certificates with fewer than 14 days left. It failed for this one, for the same reasons issuance fails (DNS moved, port 80 closed, a CDN redirecting the challenge), or the job is turned off.

How to fix

1. Open the Certificates tab of the Domains page. The row shows the last error, and the Automatic renewal card shows whether the job is on and how its last run went.
2. Fix the cause, then press Renew certificate on the row, or Renew {n} due to renew every due certificate at once.
3. If the card says the renewal job is turned off, open it with Open renewal job and enable it.

Uploaded certificates (Auto-renew: Manual) are never renewed by Synq and send no reminder: upload a new one before the old one expires.

Uploading a certificate fails

"Invalid certificate: ..." means the certificate didn't pass the checks Synq runs before touching the edge: it must parse as PEM, the private key must match it, it must cover the hostname, and it must not be expired. Paste the full chain (your certificate first, then the intermediates) and the key that belongs to it. Nothing changes on the server when an upload is refused.

DNS and SSL are fine, but the app returns 404 or 502

A certificate proves the name reaches the server; it doesn't prove the route in front of your app is right.

• A 502 page titled "Application unavailable" means the edge couldn't reach the app: it's restarting, it crashed, or it doesn't listen on the mapped port. Check the internal target on the Domains page (for example https://app.example.com -> http://web:3000) against the port your app listens on, and read the app's logs.
• A 404 page titled "Service not found" means no route exists for that hostname on this server. Use Retry routing on the project's Domains & Routes tab.
• A 503 page "... is not deployed yet" or "... is not live" means the domain is ready but the project has no live deployment. Deploy it (or read the failed deploy's log).
• For a Compose project, map the domain to the intended service's container port on Domains & Routes. A project-level domain without a port is skipped with a warning naming the available ports.
• A static route serves the release directory of the active deployment. A warning that no static root exists means the deployment's files need a new successful deployment.

If setup recorded SYNQ_PUBLIC_URL as external ingress, Synq assumes an existing proxy terminates TLS for the panel and doesn't set up its own edge for it. Use the setup flow to hand ingress to Synq's edge if that changes.

External ingress: your proxy terminates TLS

How to fix

1. Add the domain with External ingress & TLS turned on. From the API, pass "externalIngress": true on POST /api/domains.
2. No DNS record is requested or checked. Point DNS at your proxy.
3. Press Verify. The domain is verified straight away with the SSL state External TLS. Your proxy must forward requests to the Synq server on port 80 and serve HTTPS itself.

See Cloudflare Tunnel and external proxies.

Custom config was rolled back

"The edge rejected this config, so the previous config was restored." means your directives passed Synq's checks but openresty -t or the reload failed. The error underneath is nginx's own, for example a duplicate directive (often one that is also set in the project's Routing card) or an unknown directive. Nothing changed on the server. Fix the snippet and save again; see Custom proxy config.

The hostname is refused

If Add domain is rejected before verification, the hostname failed a basic check: Domain "app.example.com" is already in use (it's attached elsewhere) or "..." is not a valid public hostname. (a bare IP, localhost, a single-label name, or a label longer than 63 characters). A free subdomain (<slug>.<domain>) is saved as an ordinary custom domain, so it goes through the same checks.