DocsICP FilingConsole
Documentation
Home Page CDN Support Feature usage CNAME configuration troubleshooting guide

CNAME configuration troubleshooting guide

Updated at:
Copy as MD
Product
My Favorites

This topic describes how to troubleshoot CNAME configuration and resolution anomalies.

Basic self-check: distinguish resolution anomalies from access anomalies

A CNAME (Canonical Name) record is an alias record in DNS resolution that maps one domain name to another domain name (the CNAME domain), which is then resolved to the IP address of the server to be accessed. If you have not configured a CNAME, obtain the CNAME address assigned to your accelerated domain name from the CDN console and configure the resolution record at your DNS provider. For information about how to obtain the address, configure the record, and understand DNS resolution principles, see Quick start to Alibaba Cloud CDN.

When the console status is abnormal or access fails, first query the DNS resolution result from the client network where the problem occurs. An independently added accelerated domain name should use its dedicated CNAME; a subdomain that is covered only by a wildcard configuration should use the CNAME assigned to that wildcard domain.

Windows query command

Open the Command Prompt, query the CNAME record of the accelerated domain name, and replace the placeholder with the actual domain name:

nslookup -type=CNAME <accelerated domain name>

Linux or macOS query command

Open Terminal and use dig to query the accelerated domain name. Choose one of the following commands depending on whether you need to view the DNS response status:

  • Query only the CNAME target: Use it to compare the result with the expected address. If there is no output, switch to the detailed query.

dig +short <accelerated domain name> CNAME

  • View the DNS response status and answer: Use this to distinguish NXDOMAIN, no CNAME answer, and other DNS errors.

dig <accelerated domain name> CNAME

Check the status and ANSWER SECTION in the response.

Query result interpretation:

  1. Confirm the response status and records: Check the status and the ANSWER SECTION in the DNS response to make sure valid resolution records are returned.

  2. Compare the query result: Match the returned full CNAME address against the expected address from the console. A result that merely contains the string kunlun is not sufficient proof that the configuration is correct.

    • For example, if the expected address is cdn.example.com.w.alikunlun.com., the trailing dot (.) indicates a fully qualified domain name (FQDN) and is normal.

    • A single successful CNAME match only means that the current Local DNS resolution is normal. Because DNS caches and application-layer paths vary by region, you must also verify business availability through actual HTTP/HTTPS requests. A ping test only reflects network-layer connectivity and cannot replace CNAME verification or application-layer probing.

Based on the DNS query and actual request results, continue troubleshooting and preserve evidence as follows:

CNAME result is inconsistent or empty:

CNAME is correct but access fails:

  • If there is no HTTP response, the failure may occur during the TLS handshake or certificate validation. Record the specific error from the browser or curl, and follow the HTTPS troubleshooting guide to troubleshoot.

  • If an HTTP response is returned, use the browser developer tools to view the actual HTTP status code, response headers, and error information, and compare them with the CDN and origin logs. If necessary, continue locating the specific cause by following the origin-fetch troubleshooting guide. A 5xx status code may be caused by the origin-fetch path or a gateway timeout, and you must check the logs to confirm whether the origin server itself is at fault.

Only some regions or clients experience anomalies:

Record the time, region, DNS resolver, resolution result, full URL, HTTP status code, response headers, and error information for both normal and abnormal requests. After comparing the differences and identifying the root cause (DNS, client, CDN configuration, or origin server), perform the fix. During troubleshooting, keep the existing public DNS configuration and domain enabled to avoid altering the failure state or causing secondary failures.

Resolution result anomalies

CNAME query returns NXDOMAIN, no result, or an unexpected target

This applies when a CNAME query reports that the domain name does not exist, returns no target address, or returns an unexpected target. When such an anomaly occurs, check the DNS configuration, authoritative resolution result, and cache state directly. The empty output of dig +short hides status-code details, so use the full query command for troubleshooting.

Troubleshooting directions:

  • Distinguish the DNS response status: Use the detailed query command in Basic self-check (Linux or macOS) to view the status. NXDOMAIN means the authoritative DNS has determined that the name does not exist. If the response also contains a CNAME chain, follow the CNAME chain level by level. A status of NOERROR with no corresponding answer is a no-data response (NODATA) only after a referral is ruled out; investigate it differently from a non-existent domain. SERVFAIL, REFUSED, or a query timeout indicates a resolver service anomaly, and you should prioritize checking the authoritative DNS service and the local resolver.

  • Check the name and authoritative DNS configuration: Confirm that the queried domain name is spelled correctly, and check the record name, type, target address, and resolution line with the DNS provider that actually hosts the domain. For example, when using Alibaba Cloud DNS to configure a record for cdn.example.com, the host record is usually cdn. Some third-party DNS providers may require a relative name or a full name, so confirm the final record name according to their input rules.

  • Compare the authoritative DNS and Local DNS results: First confirm the authoritative DNS server for the DNS zone that owns the name with your DNS provider, and then query that server directly. Replace the placeholders with the corresponding server and actual domain name:

    dig @<authoritative DNS server> <accelerated domain name> CNAME +norecurse

    Confirm that the response contains the authoritative flag aa, and compare the result with the query result from the Local DNS used by the client. If the authoritative DNS does not return the expected record, re-check the console configuration. If the authoritative DNS already returns the new record but the Local DNS still returns the old result, it is a cache issue. In split-horizon resolution scenarios, you also need to verify in the network environment corresponding to the target line.

  • Troubleshoot NOERROR but no CNAME result: Confirm whether the name is originally configured with only A or AAAA records, or whether the DNS provider has enabled CNAME flattening or another mechanism that returns IP addresses externally. For the latter, follow the record conflict and flattening judgment method to check the configuration and actual access. When a wildcard domain is involved, also check whether the subdomain is actually using the wildcard DNS record in Wildcard CNAME and subdomains.

CNAME query for the same domain points to multiple targets

A single DNS query returns multiple CNAME records, or different regions or resolvers (Local DNS) return different CNAME targets. When troubleshooting, distinguish among same-name multi-value conflicts, CNAME alias chains, and split-horizon resolution.

Troubleshooting directions:

  • A single response contains multiple CNAME targets for the same domain name (same-name multi-value conflict): Check the DNS configuration of the domain name for the corresponding line, investigate whether there is an invalid multi-value configuration or an abnormal response from the DNS provider, and retain only the correct record. If access errors also occur, you must still confirm the HTTP status by making actual requests after fixing the DNS conflict.

  • A single response contains multiple CNAME records that point step by step (CNAME alias chain): If the returned records form a progression such as "A points to B, and B points to C" (for example, a.example.com → b.example.com → final target), this is a normal CNAME chain, not duplicate configuration. Check the accuracy of each segment in order, and focus on confirming the final resolved IP address and whether actual HTTP/HTTPS access is normal.

  • Different regions or resolvers return different CNAME targets (split-horizon resolution): When each query location returns a unique but different target, intelligent or split-horizon resolution is usually configured (for example, by ISP or region), or there are local DNS cache differences. This is a normal scheduling mechanism, not a multi-value conflict in a single response. First check the expected targets for each resolution line in the authoritative DNS console, and compare the DNS cache status in each region. Do not blindly delete normal records for other lines without distinguishing the resolution line, or you may interrupt service in the corresponding region.

Record configuration and console status anomalies

Configuring CNAME reports a record conflict, or only A/AAAA records are found

A DNS provider prompt indicating that the same name has a record conflict, and a query that returns no CNAME but only IP addresses, are two different issues and must be investigated separately.

Troubleshooting directions:

  • There is an explicit configuration conflict prompt: Check the conflicting record name, type, and resolution line according to the DNS provider prompt. Standard CNAME records cannot coexist with ordinary A, AAAA, MX, or TXT records of the same name. If the original record carries a service that cannot be interrupted (for example, an MX mail record on the apex domain), we recommend using a non-conflicting subdomain to connect to CDN.

  • No conflict prompt, but the query returns only A or AAAA: First check the actual configuration at the DNS provider. If it is configured as A or AAAA, verify whether it matches the current connection plan. If it is configured as CNAME but the provider has enabled flattening (CNAME flattening) or a similar mechanism, the authoritative DNS may directly return the final resolved IP address to clients, hiding the intermediate CNAME chain.

  • Verify the ownership of the returned IP: Query the IPv4 and IPv6 resolution results for the name from the client network where the problem occurs, and check the returned addresses:

    dig <accelerated domain name> A
dig <accelerated domain name> AAAA

    Combine this with the DNS console configuration to confirm whether the returned IP address is the result of resolving the CNAME target. You can also use the IP detection tool in the CDN console to verify whether the returned IP belongs to an Alibaba Cloud CDN node.

  • Confirm the conflict before planning a switch: First verify the website, mail, or other services carried by the original record, keep the existing resolution, complete CDN access testing, and back up the records before evaluating how to adjust. You can also choose a subdomain that does not carry conflicting business records to connect. For the full onboarding and DNS configuration process, see Quick start to Alibaba Cloud CDN.

    Important

    Deleting or pausing A/AAAA records may interrupt existing access. Adjusting MX or TXT records may affect mail delivery or domain authentication. Confirm the business dependencies and switch plan, and perform the operation during off-peak hours.

Console CNAME status is inconsistent with resolution

Symptom: The DNS record has been modified, but the CNAME status in the console still shows Configuring, Not Configured, or Verification failed.

Troubleshooting directions:

First distinguish domain status from CNAME status: On the Domain Names page in the CDN console, a domain status of Configuring means the configuration is being deployed (if acceleration has been stopped, first check the stop reason). A CNAME status of Not Configured only means the console detection mechanism has not yet confirmed that public DNS resolution is effective.

Troubleshooting directions:

  • The query result does not match the expected address or is empty: Follow Basic self-check to judge the DNS response, compare the full CNAME address and the trailing FQDN dot (.), and then check the host record, record value, and resolution line configuration in the authoritative DNS.

  • The authoritative DNS has been updated, but Local DNS still returns the old record: Check the remaining TTL of the old record or negative-cache effects, and then query again to verify. If the command-line resolution already matches the expected result but the console status is slightly delayed, refresh the console page later.

  • Split-horizon DNS resolution is configured: Query from the actual network environment of the target users, and record the Local DNS used, the resolved target address, and the business request result. To judge whether a line is usable, both "the line returns the expected CNAME record" and "actual HTTP/HTTPS business requests are normal" must be satisfied. A single detection result or the acceleration region setting in the console cannot represent the actual access state of all users on all lines.

If the DNS resolution result already matches the expected result but business requests are still abnormal, continue to check actual requests and logs by following Basic self-check. If the results remain inconsistent, keep the detection time, resolver, DNS answer, and request evidence for further locating.

Subdomain resolution and access anomalies

www subdomain access is abnormal or the configuration is not effective

Symptom: The subdomain www.example.com cannot be accessed, or www has been independently added as an accelerated domain name but its configuration is not effective.

Root cause: www.example.com and the apex domain example.com are independent request domain names. Even if the apex domain is accessible, you must still check the DNS resolution and CDN configuration of the www subdomain separately.

Troubleshooting directions:

  • Check whether CDN configuration covers www: Confirm that www.example.com is added in CDN, or that a wildcard domain *.example.com that covers it is added. If www is not independently added but is effectively covered by a wildcard configuration, www can use the CNAME assigned to that wildcard domain and does not need to be added as an exact accelerated domain name. Adding only the apex domain example.com does not automatically cover www.

  • Check the actual DNS answer for www: Query www by following Basic self-check, and compare the result with the expected full CNAME address. If www has been independently added as an accelerated domain name, it should use its dedicated CNAME. If it is not independently added but is effectively covered by a wildcard configuration, it should use the wildcard CNAME. If the result is empty, first check the response status and whether the DNS provider has enabled flattening.

  • Check the actual request for www: If the resolution matches the expected result but access still fails or the configuration is not effective as expected, record the full URL, HTTP status code, response headers, and logs for www requests. If the apex domain is accessible, compare its request result. Continue to locate client, CDN configuration, or origin-fetch issues by following Basic self-check. During troubleshooting, keep the existing public DNS resolution to preserve the failure scene. You can test the origin server directly by editing the local Hosts file.

When DNS still points to the wildcard CNAME, the exact-domain configuration is not effective

This applies when both the exact domain www.example.com and the wildcard domain *.example.com are added in CDN, but the DNS resolution of www still points to the wildcard CNAME. If www is not independently added and is accelerated only by the wildcard domain, www using the wildcard CNAME is a normal configuration.

CDN assigns a corresponding CNAME address to each accelerated domain name. After www.example.com is independently added as an accelerated domain name, CDN assigns a dedicated CNAME to it, which is different from the CNAME of the wildcard domain *.example.com.

When both an exact domain and a wildcard domain are added, the configuration that takes effect for a request is determined by the CNAME that DNS resolution points to: a request that resolves to the dedicated CNAME of www is processed according to the exact-domain configuration of www; a request that resolves to the wildcard CNAME is processed according to the wildcard configuration.

Therefore, when www still resolves to the wildcard CNAME, CDN processes the request according to the wildcard configuration. The origin server, cache rules, HTTPS certificate, and access control settings configured separately on the exact domain www will not take effect for this request.

If www has been independently added as an accelerated domain name but still resolves to the wildcard CNAME, the console verification will find that www has not resolved to its dedicated CNAME, so the CNAME status of the domain may show Not Configured or Configuring.

Identify the cause and take action:

  • If www is not covered by a CDN configuration, add www as an accelerated domain name or add the corresponding wildcard domain, and use the CNAME assigned by that configuration. For the onboarding operation, see Quick start to Alibaba Cloud CDN.

  • If the CDN configuration covers www correctly but the DNS answer does not match the expected result, adjust the record for the corresponding name and line at the DNS provider. If existing business records are involved, first evaluate the impact by following the record conflict handling method. If the DNS answer matches the expected result, handle the problem corresponding to the actual request.

  • If www has been independently added but still resolves to the wildcard CNAME, and you want the exact-domain configuration of www to take effect, first evaluate the impact on existing business and back up the DNS records, then change the CNAME target of the corresponding line for www to the dedicated address assigned by CDN for www. After the change, compare the authoritative DNS and Local DNS answers, and verify whether actual requests are processed according to the source, cache, HTTPS certificate, and access control configuration of www.

After configuring a wildcard CNAME, some subdomains still resolve to the old address or return no CNAME result

This applies when a wildcard DNS record has been configured, but specific subdomains such as a.example.com and b.example.com do not return the expected CNAME. The DNS wildcard determines how DNS responses are generated, and the CDN accelerated domain name configuration determines whether the request domain is covered. These two must be checked separately.

Troubleshooting directions:

  • Check whether the specific name is using the wildcard DNS record: Query the subdomain that is actually accessed, and check the exact DNS record of the same name at the DNS provider. An existing name does not automatically use the wildcard record just because it has no CNAME record. Check all A, AAAA, TXT, and other records of the same name. If a same-name record is found, first verify the services it supports, and do not delete it without evaluating its impact, or you may interrupt existing services.

  • Check the DNS matching scope, line, and cache: Do not assume that all subdomains without individual records inherit the wildcard DNS record. Existing more specific DNS names also affect wildcard matching. Verify whether the name matches the current wildcard according to the DNS provider rules, and then compare the authoritative DNS and target-line resolution results by following the DNS response and cache troubleshooting method.

  • Check whether CDN covers the actual request domain:

    Check whether the corresponding domain is added and covered in the CDN console:
    Configuring *.example.com at the DNS provider only completes domain name resolution. You must also make sure the corresponding wildcard or exact domain is added in the CDN console:

    • For ordinary same-level subdomains (for example, www.example.com): If *.example.com in the CDN console covers it, use the wildcard CNAME directly. If it has been independently added as an exact domain, use its dedicated CNAME (follow the exact-domain configuration not effective troubleshooting method).

    • For multi-level subdomains (for example, sub.a.example.com): Even if some DNS providers can return resolution results for multi-level subdomains through wildcards, the CDN wildcard configuration (for example, *.example.com) only supports matching subdomains at the same level. If you need to accelerate deeper subdomains, see Quick start to Alibaba Cloud CDN to add an accelerated domain name at the corresponding level in the console.

Note

Whether an exact DNS record prevents a wildcard from generating an answer is a matter of DNS resolution matching. Whether CDN has configured the corresponding accelerated domain name is a matter of request-domain coverage. These two are independent. If the resolution already matches the expected result but access is still abnormal, check the actual HTTP/HTTPS request path by following Basic self-check.

Previous：Feature usageNext：Verify whether CDN is in effect