Troubleshooting Guide for Subdomain Configuration in Onetagger

5 dagen geleden bewerkt

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 dit artikel nuttig?