Domains & Custom Hostnames

Custom Hostname Troubleshooting

Custom Hostname Troubleshooting

This guide covers common issues when setting up custom hostnames for your Digital Product Passports.

DNS Not Propagating

Symptoms

  • Custom hostname returns connection errors
  • dig or nslookup does not show your CNAME record

Solutions

  1. Verify the CNAME record is correctly configured at your DNS provider
  2. Check for conflicting records — ensure no A record exists for the same subdomain
  3. Wait for propagation — DNS changes typically take effect within an hour but can take up to 24–48 hours depending on your provider and previous TTL settings
  4. Use a DNS checker — tools like dnschecker.org can verify propagation across regions

TLS Certificate Not Provisioning

Symptoms

  • Browser shows SSL/TLS errors
  • Status shows “Activating” for an extended period
  • curl reports certificate issues

Solutions

  1. Ensure CNAME is correct — must point to <brand>.tieback.io
  2. Check CAA records — if your domain has CAA records, ensure they allow certificate issuance by the providers used by Cloudflare
  3. Wait — certificate provisioning typically takes 5–15 minutes after DNS propagation
  4. Contact support if activation has not completed after 48 hours

Custom Hostname Returns 403 Forbidden

Cause

You are accessing a non-public path on a custom hostname. This is expected behaviour.

Explanation

Custom hostnames support public consumer paths only:

  • ✅ /01/<GTIN> — resolver path (supported)
  • ✅ /mu/<id>, /mb/<id>, /ml/<id> — resolver paths (supported)
  • ✅ /p/<id> — public passport page (supported)
  • ❌ /dashboard, /settings, /app, etc. — returns 403

Solution

Use your platform subdomain (<brand>.tieback.io) for dashboard and application access. Custom hostnames are designed for consumer-facing passport resolution and viewing only.

Custom Hostname Returns 404 Not Found

Possible Causes

  1. Product not found — the GTIN or identifier does not exist in your product catalogue
  2. Product not minted — the product exists but has no minted tokens
  3. Hostname not verified — the custom hostname has not been verified in the tieback platform
  4. Incorrect GTIN — verify the GTIN in the URL matches your product

Solutions

  1. Check the product exists in your tieback dashboard
  2. Ensure the product has been minted with at least one token
  3. Verify the custom hostname in Settings → Domains

CNAME Target Is Wrong

Common Mistakes

❌ Incorrect Target✅ Correct Target
tieback.io<brand>.tieback.io
app.tieback.io<brand>.tieback.io
www.tieback.io<brand>.tieback.io
An IP address<brand>.tieback.io

The CNAME must point to your brand’s specific platform subdomain.

Custom Hostname Not Active Yet

If your custom hostname has not been verified and activated in the tieback platform:

  • Resolver paths will return 404 (the hostname is not recognised as belonging to a brand)
  • The scan will not resolve to a passport

Ensure you have completed the verification process in Settings → Domains before testing.

Platform Subdomain Fallback

Your platform subdomain (<brand>.tieback.io) always remains active. If you experience issues with your custom hostname:

  • Existing QR codes using the platform subdomain will continue to work
  • You can switch back to platform subdomain URLs at any time
  • Both platform subdomain and custom hostname can be active simultaneously

Support Escalation

If you’ve followed this guide and still experience issues:

  1. Gather your DNS configuration (screenshot or export)
  2. Note the exact URL that is failing
  3. Note the HTTP status code and any error messages
  4. Contact support with this information