Troubleshooting Custom Domains
Use this guide when an Imgwire custom image delivery domain is stuck in PENDING, fails certificate validation, returns delivery errors, or cannot be created.
Requirements
Custom domains have a few constraints:
- Each Environment can have one custom domain.
- Custom domains must be subdomains, such as
cdn.example.comorimages.example.com. - Do not use an apex/root domain such as
example.com. - You need access to the hostname's DNS settings.
- Your organization plan must have custom domains enabled.
- A hostname can be claimed by only one Imgwire custom domain.
Create and inspect the custom domain from the dashboard or through the Custom Domain Resource API.
Domain cannot be created
If creation fails, check the hostname first.
Valid hostname input:
images.example.com
Invalid hostname input:
https://images.example.com/path
images.example.com:443
example.com
Imgwire expects a hostname only, without protocol, path, query string, fragment, whitespace, or port.
If you receive PaymentRequiredError, your current plan may not include custom domains. If you receive a conflict error, the hostname may already be claimed by another Environment.
Domain is stuck in PENDING
After creating a custom domain, Imgwire returns two DNS records:
| Field | Purpose |
|---|---|
cname_record | The hostname you want to use for delivery |
cname_value | The target your hostname should CNAME to |
dcv_cname_record | Domain control validation record |
dcv_cname_value | Domain control validation target |
Add both returned CNAME records exactly as shown by Imgwire. DNS providers differ in how they display record names, so verify the fully-qualified result after saving.
After DNS changes are live, re-check the connection:
curl https://api.imgwire.dev/api/v1/custom_domain/test_connection \
-X POST \
-H "Authorization: Bearer $IMGWIRE_API_KEY"
Use the default Imgwire CDN URL until the custom domain returns status: CONNECTED and certificate_status: ACTIVE.
Certificate is not active
Certificate validation depends on the domain control validation record. If certificate_status stays PENDING or changes to FAILING:
- Confirm the
dcv_cname_recordexists in public DNS. - Confirm it points to the exact
dcv_cname_valuereturned by Imgwire. - Remove conflicting records for the same validation hostname.
- Wait for DNS propagation, then run
test_connectionagain. - Keep the default CDN URL in production until the certificate is active.
Custom domain connects but images do not load
If the custom domain is connected but image URLs fail:
- Test the same image on the default CDN hostname.
- Generate the custom-domain URL with an SDK helper, CLI command, or documented URL pattern instead of manually rewriting the default CDN URL.
- Confirm the image record is
READY. - Confirm transformation query parameters work on the default CDN URL.
- Check that the hostname you are using matches the Environment where the image exists.
Status fields
| Field | Healthy value | Other values |
|---|---|---|
status | CONNECTED | PENDING, FAILED |
certificate_status | ACTIVE | PENDING, FAILING |
last_verified_at | Date-time | null before verification |
Common mistakes
- Using an apex/root domain instead of a subdomain.
- Adding only the routing CNAME and missing the DCV CNAME.
- Using DNS values from an old custom domain after deleting and recreating the domain.
- Replacing production image URLs before certificate validation is active.
- Trying to attach the same hostname to more than one Environment.
Related pages
Last updated at: May 8, 2026