For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
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
Verify the CNAME record is correctly configured at your DNS provider
Check for conflicting records — ensure no A record exists for the same subdomain
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
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
Ensure CNAME is correct — must point to <brand>.tieback.io
Check CAA records — if your domain has CAA records, ensure they allow certificate issuance by the providers used by Cloudflare
Wait — certificate provisioning typically takes 5–15 minutes after DNS propagation
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:
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
Product not found — the GTIN or identifier does not exist in your product catalogue
Product not minted — the product exists but has no minted tokens
Hostname not verified — the custom hostname has not been verified in the tieback platform
Incorrect GTIN — verify the GTIN in the URL matches your product
Solutions
Check the product exists in your tieback dashboard
Ensure the product has been minted with at least one token
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:
Gather your DNS configuration (screenshot or export)