Source: https://atomic-works-test.docs-staging.pageloop.ai/product/platform-administration/workspace-setup/custom-domain-troubleshooting # Custom domain: Troubleshooting If your custom domain is stuck in a pending state, the portal is not loading over HTTPS, or your domain stopped working unexpectedly, use this guide to diagnose the most common causes and fixes. For initial setup steps, see [Setting up a custom domain for your portal](/product/platform-administration/workspace-setup/setting-up-a-custom-domain-for-your-portal). ## Quick reference: setup stages Your custom domain moves through three stages after you add your DNS records: | Stage | What's happening | Typical duration | | ----------- | --------------------------------------------------------------- | ------------------------------------------ | | Pending DNS | Atomicwork is waiting for your DNS records to be detected. | 1-5 minutes, occasionally up to 30 minutes | | Pending SSL | DNS is verified and Atomicwork is issuing your SSL certificate. | A few minutes | | Connected | Your custom domain is live and secured with HTTPS. | No action needed | SSL certificates are issued through Let's Encrypt and renewed automatically before they expire. There is nothing for you to manage or monitor. ## Verify your DNS records If your domain is stuck on **Pending DNS** for more than 30 minutes, first confirm your DNS records resolve correctly. ### Option 1: Use an online tool Visit [dnschecker.org](https://dnschecker.org) and enter your custom domain, such as `help.yourcompany.com`. 1. Select **CNAME** from the dropdown. The result should match the Atomicwork target shown on your Domains page, such as `yourorg.atomicwork.com`. 2. Switch the dropdown to **TXT** and enter the verification name from your Atomicwork settings. It starts with `_atomicwork-verify.`. The result should match the verification value shown in Atomicwork. Empty or mismatched results mean your DNS records have not been applied correctly. ### Option 2: Use the command line On macOS or Linux, check your CNAME record: ```bash dig CNAME help.yourcompany.com +short ``` Expected result: ```text yourorg.atomicwork.com. ``` Then check your TXT verification record: ```bash dig TXT _atomicwork-verify.help.yourcompany.com +short ``` Expected result: ```text "atomicwork-verification=your-verification-code" ``` On Windows, use Command Prompt: ```bat nslookup -type=CNAME help.yourcompany.com nslookup -type=TXT _atomicwork-verify.help.yourcompany.com ``` Replace the example domains with your actual domain and the values shown on your Atomicwork Domains page. ## Common issues ### "Pending DNS" will not clear **Symptoms:** The status indicator stays on **Pending DNS** for longer than 30 minutes after you add your DNS records. **Cause:** Either the CNAME or TXT record was entered incorrectly, or DNS propagation has not completed yet. **Fix:** 1. Open your DNS provider and confirm the **CNAME** record: - **Name / Host** matches what Atomicwork shows. Usually this is just the subdomain, such as `help`, not `help.yourcompany.com`. - **Value / Target** matches exactly, such as `yourorg.atomicwork.com`. 2. Confirm the **TXT** record: - The name includes the special prefix `_atomicwork-verify.`. Do not strip it. - The value matches what Atomicwork shows. 3. If you recently changed records and the previous record had a high TTL, give it time to propagate. Setting TTL to 5 minutes, or 300 seconds, when adding new records helps future changes apply faster. ### SSL stays on "Pending SSL" **Symptoms:** DNS verification completed, but the status indicator is stuck on **Pending SSL** for more than a few minutes. **Cause:** Cloudflare's proxy is intercepting the certificate challenge, or a CAA record on your domain is blocking Let's Encrypt. **Fix:** 1. **If you use Cloudflare:** Open your Cloudflare DNS settings, find the CNAME record for your custom domain, and change the proxy status to **DNS only**, shown as the grey cloud icon. The orange cloud, Cloudflare's proxy, interferes with SSL issuance. SSL usually completes within a few minutes after switching to the grey cloud. 2. **Check your CAA record:** On [dnschecker.org](https://dnschecker.org), select **CAA** from the dropdown and look up your root domain. If a CAA record exists, it must include `letsencrypt.org` as a permitted issuer. If no CAA record exists, this is not the cause. ### Domain was working but stopped **Symptoms:** Your custom domain previously connected successfully, but the portal is no longer loading or shows a certificate error. **Cause:** A DNS record was inadvertently removed or modified, or Cloudflare's proxy was re-enabled on the CNAME record. **Fix:** 1. Open your DNS provider and verify both the CNAME and TXT records are still present and unchanged. 2. If you use Cloudflare, confirm the CNAME record is still set to **DNS only**, shown as the grey cloud. 3. Atomicwork renews SSL certificates automatically, so an expired certificate is not a likely cause unless the DNS records changed and broke renewal validation. ## DNS provider tips Different DNS providers handle CNAME and TXT records slightly differently. Watch for these provider-specific details: - **Cloudflare:** Set the proxy to **DNS only**, shown as the grey cloud, on the CNAME record. The orange cloud blocks SSL issuance. - **GoDaddy:** In the **Host** field, enter only the subdomain, such as `help`, not the full domain. GoDaddy appends the root domain automatically. - **AWS Route 53:** Paste the target value exactly as Atomicwork shows it. Route 53 handles the formatting. - **Namecheap:** For the TXT record, the **Host** field should not include your root domain. If Atomicwork shows `_atomicwork-verify.help.yourcompany.com`, enter only `_atomicwork-verify.help`. - **Google Cloud DNS:** Works as expected; no special handling is needed. Most DNS providers want only the subdomain in the **Name** or **Host** field and append your root domain automatically. When in doubt, check your provider's documentation. ## Still need help? If your DNS records check out and the domain has been stuck in a pending state for more than an hour, contact Atomicwork support with: 1. Your custom domain name 2. A screenshot of your DNS records from your provider 3. The output from [dnschecker.org](https://dnschecker.org) or the `dig` commands above