Troubleshooting Guide for Subdomain Configuration in Onetagger

Edited 5 days ago

When configuring your custom subdomain for Onetagger, you might run into issues. This guide will help you methodically diagnose and resolve them, so you can launch your server-side tagging container confidently.

1️⃣ DNS verification failed

Possible causes:

  • Incorrect or incomplete DNS record.

  • Wrong record type (A vs. CNAME).

  • Incorrect IP or hostname.

  • DNS changes not yet fully propagated.

How to resolve:

  • Double-check the Type, Name, and Value in your DNS provider dashboard.

  • Confirm you saved all changes and that there are no conflicting records.

  • Verify the correct IP or hostname exactly as shown in your Onetagger setup screen.

  • Check propagation using WhatsMyDNS. Full propagation can take up to 24 hours.

2️⃣ Subdomain shows a 404 or unexpected content

Possible causes:

  • Subdomain pointing to an old or incorrect record.

  • DNS conflicts with other services.

  • Local browser or DNS cache issues.

How to resolve:

  • Remove or correct any conflicting DNS records.

  • Clear your browser cache or try incognito/private mode.

  • Flush your local DNS cache (e.g., ipconfig /flushdns on Windows, sudo dscacheutil -flushcache; sudo killall -HUP mDNSResponder on macOS).

  • Visit your subdomain’s /healthz endpoint directly (e.g., https://your-subdomain.mywebsite.be/healthz).

    • You should receive a 200 OK status code and see the text ok.

    • If you do not see this, your DNS or server routing is not correctly configured.

3️⃣ Validation spinning or stuck

Possible causes:

  • Network-level blocking (firewalls, VPNs).

  • Browser extensions interfering.

  • DNS propagation not completed.

How to resolve:

  • Temporarily disable browser extensions (ad blockers, privacy tools).

  • Try from a different network (e.g., mobile hotspot).

  • Check DNS propagation and ensure at least 24 hours have passed.

4️⃣ SSL certificate errors

Possible causes:

  • DNS not fully propagated before SSL issuance.

  • Conflicting DNS entries or misconfigured DNSSEC.

  • IP mismatches.

How to resolve:

  • Wait up to 24 hours for DNS changes before SSL issuance completes.

  • Make sure your subdomain consistently resolves to the correct IP globally.

  • Verify DNSSEC settings (disable temporarily if needed).

  • Contact Onetagger support to reissue the certificate if issues persist.

5️⃣ "Subdomain already in use" error

Possible causes:

  • The subdomain is already assigned to another container or system.

  • DNS is pointing somewhere else.

How to resolve:

  • Check your existing Onetagger containers to confirm if this subdomain is already linked.

  • Remove or update conflicting DNS records.

  • Reassign or create a new subdomain if needed.

🩺 Extra diagnostic step: Check /healthz

The /healthz endpoint is a direct, quick way to confirm your subdomain is correctly set up and operational.

How to use it:

  1. Open your browser and go to:
    https://your-subdomain.mywebsite.be/healthz

  2. You should see:

    • A plain text response: ok

    • HTTP status code: 200 OK

  3. If you see anything else (errors, blank page, or different content), re-check your DNS and server routing settings.

Additional tips

✅ Document all changes and keep backup copies of old DNS records.
✅ Start with a test subdomain if you're unsure.
✅ Involve IT or DevOps early to reduce setup friction.

When to contact support

If the above steps don’t resolve your problem, contact Onetagger support with:

  • Your domain and subdomain details.

  • Screenshot(s) of your DNS configuration.

  • Copy of the response (including status code) from your /healthz check.

  • Any dashboard error messages.

Was this article helpful?