CDN:Cache troubleshooting

Troubleshooting steps:

1. Confirm that the configuration has taken effect: After you add or modify a cache rule, the rule status shows Configuring, which means the configuration is being delivered to POPs worldwide. The status usually changes to Success within a few minutes. Do not rush to verify the rule before the configuration takes effect.

2. Confirm that the new rule applies to the target resource: A new rule applies only to new requests. Resources already cached on POPs continue to be served under the previous policy until they expire. To apply the rule immediately, first clear the previous cache by using Refresh and prefetch.

3. Check the rule matching priority: When a request matches multiple rules, only one rule takes effect. By default, the rule with the higher weight takes precedence. When the weights are equal, the rule created later usually takes precedence (refer to the actual description in the console). Make sure that the rule matched by the target path has the highest weight. For example, the weight of a specific directory (/static/) should be higher than that of the root directory (/).

4. Check whether the origin response headers prohibit caching: If the origin server returns Cache-Control: no-cache, no-store, max-age=0, or Pragma: no-cache, CDN follows the origin directive by default. For the impact of different directives on origin fetch behavior, see the following table. You can enable Ignore no-cache headers from the origin server in the cache rule to enforce caching based on the console rules, or adjust the origin server configuration to remove the no-cache directives for static resources.

5. Check how URL parameters are processed: If the URL contains parameters and Ignore parameters is disabled, URLs with different parameters are treated as different resources, which reduces the cache hit ratio. You can enable Ignore parameters or Retain specified parameters.

6. Check whether the root directory is misconfigured as not cached: If the rule for the root directory / has the highest weight and an expiration time of 0 seconds, all requests trigger origin fetch.

In step 4 above, different no-cache directives from the origin server have significantly different impacts on origin fetch behavior. Assess the load on the origin server based on the actual directive:

Origin response header	CDN behavior	Impact on the origin server
Cache-Control: no-store	Caching is completely prohibited. Every request fetches the full resource from the origin server.	The origin server bears all traffic pressure.
Cache-Control: no-cache or max-age=0	POPs are allowed to store cache copies, but they must revalidate with the origin server before each use. When validation passes, the origin server returns 304 (without a response body), and the overhead is far less than a full origin fetch.	The number of origin fetches does not decrease, but each fetch is only a small conditional request, so the bandwidth pressure is manageable.
Pragma: no-cache	An HTTP/1.0 compatibility directive. The effect is similar to no-cache.	Same as above.

The purpose of setting the expiration time to 0 is to make every request fetch the latest content from the origin server. If earlier content is still returned, troubleshoot as follows:

1. Rule out the local browser cache: Clear the browser cache or use private browsing mode to test again, and confirm that the POP rather than the browser returns the earlier content.

2. Clear the cache that existed before the configuration change: Resources cached before you modified the configuration are not cleared automatically. Submit a URL refresh task by using Refresh and prefetch.

3. Check whether the origin server has its own cache: The origin server (for example, an Nginx cache or an application-layer cache) may return earlier content, so CDN fetches stale data during origin fetch.

4. Confirm that the configuration has taken effect worldwide: The rule status must be Success. Delivering the configuration to all POPs takes a few minutes.

5. Confirm that the request hits the expected POP: Users of different ISPs or in different regions may hit different POPs. Test in multiple regions separately, or use the CDN real-time logs and the POP IP in the response to identify the issue further.

1. Check the configuration completeness: A custom cache key usually requires setting rule conditions based on request characteristics (such as User-Agent) and then adding different cache key variables to each rule. Confirm that the request characteristics of mobile and PC clients are correctly identified, and that the matching conditions of the two rules do not overlap each other.

2. Wait for the configuration to take effect: After you submit the configuration, wait 5 to 10 minutes for it to synchronize worldwide.

3. Refresh the previous cache: Resources cached under the previous cache key before the configuration change do not expire automatically. Submit a refresh task (we recommend that you use directory refresh).

4. Verify on the client: Clear the browser cache and retry, and check whether X-Cache in the response headers is MISS.

5. Test with real devices: Send requests by using the actual User-Agent of different devices instead of only resizing the browser window (the User-Agent emulated by a browser may differ from that of a real device).

Cause: When the origin response contains the Set-Cookie response header, CDN does not cache the response by default, which results in a cache hit ratio of 0.

Recommended solutions (in priority order):

• Fix it on the origin side (recommended): Make the origin server stop returning Set-Cookie for static resources such as images, CSS, JavaScript, and fonts. This is the fundamental solution. It does not affect the session management of dynamic endpoints and improves the cache hit ratio.

• Remove it by path on the CDN side: If the origin server cannot be adjusted, remove this response header on the CDN side only for static resource paths such as /static/, *.css, and *.js to avoid affecting dynamic endpoints.

Steps to remove the header by path on the CDN side:

1. Log on to the CDN console. On the Domain Names page, find the target domain name and click Manage.

2. In the left-side navigation pane of the domain details page, click Origin Settings and go to the Modify incoming response headers tab.

3. Click Add, restrict the rule condition to the static resource paths, select Delete for the response header operation, and enter Set-Cookie for the response header name.

4. After the configuration is complete, use Refresh and prefetch to clear the cached earlier responses so that the new rule takes effect.

If the cache hit ratio still does not improve after the configuration, check the following: whether Ignore no-cache headers from the origin server is enabled in the cache rules, and whether Ignore parameters is enabled to prevent the same resource from being split into multiple cache objects due to different query parameters. For the default cache rules of CDN, see Configure CDN cache expiration.

A low cache hit ratio means that most requests trigger origin fetch. An unstable public network path can degrade the acceleration effect and put load pressure on the origin server. Troubleshoot as follows:

1. Check whether the origin server returns no-cache directives: This is the most common cause of a low hit ratio and saturated origin bandwidth. If the origin server returns Cache-Control: no-cache, no-store, max-age=0, or Pragma: no-cache, CDN follows the origin directive and does not cache the resource, so every request triggers origin fetch. You can enable Ignore no-cache headers from the origin server in the cache expiration configuration to enforce caching based on the console rules, or adjust the configuration of the origin server.

2. Check whether cache rules are misconfigured: Confirm that the cache expiration time for the root directory / is not set to 0 seconds with the highest weight. Otherwise, all requests trigger origin fetch.

3. Check whether URLs contain variable parameters: Changing parameters after the question mark in a URL cause the same content to be treated as different resources. Enabling Ignore parameters consolidates such requests into a single cache object. For more information, see the next item.

4. Configure static and dynamic resources separately: Set a long cache duration (such as 30 days) for static resources such as images, CSS, JavaScript, and fonts, and set the expiration time to 0 seconds for dynamic content such as PHP, JSP, and API endpoints.

5. Enable range origin fetch for large files: For large files such as videos and installation packages, make sure that range origin fetch is enabled so that the POP does not fetch the entire file from the origin server for every request. Before you enable this feature, confirm that the origin server supports range requests (that is, it can return 206 Partial Content). Enabling this feature when the origin server does not support range requests may cause request failures or abnormal content.

6. Check whether the business QPS is too low: POP disk space is limited, and resources that are accessed infrequently are evicted by hot resources, which triggers origin fetch. For domain names with only a dozen QPS, we recommend that you submit prefetch tasks by using Refresh and prefetch so that resources stay resident on POPs.

Symptom: The overall hit ratio of a page is low. The response headers show that X-Cache is MISS for the main request, but HIT for individual files on the page.

Cause: The URL contains parameters that change with each request, such as a timestamp. When the ignore parameters feature is disabled, CDN treats each URL with different parameters as an independent resource and cannot reuse the cache. For example, the value after ?_t= in http://example.com/movie/res/ArrowScene.ccbi?_t=1699999999 differs for every request.

Solution: Enable Ignore parameters in the CDN console. After you enable this feature, the parameters are excluded from the cache object calculation, and requests for the same resource with different parameters hit the same cache. If your business depends on some parameters, select Retain specified parameters to ignore only the irrelevant ones.

Common causes of short-term fluctuations or a continued decrease in the hit ratio:

• A cache refresh was performed: A manual or automatic refresh clears the cache on POPs, so a decrease in the hit ratio within a short period is expected. As resources are cached again, the hit ratio usually recovers automatically within a few hours.

• A bandwidth surge occurred: A sharp traffic increase within a short period brings many first-time requests, which increases origin fetch and decreases the hit ratio.

• A large amount of new content is accessed: When POPs frequently request resources that are accessed for the first time, origin fetch is inevitable and the hit ratio decreases.

• Cache rules were adjusted: Modifying the cache policy, especially shortening the expiration time, affects the hit ratio.

• URLs contain variable parameters: Changing parameters split the same content into multiple cache objects.

• The cache expiration time is not properly configured: If the configuration does not differentiate resources by update frequency, the cache expires too early.

If you have configured CORS response headers on CDN but clients still report CORS errors and the response headers do not contain the configured field, the possible causes and solutions are as follows:

• The configuration has not taken effect: Confirm that the configuration is saved and the rule status is Success.

• The configuration has not been fully delivered: Changes to the outbound response header configuration usually take effect within 5 minutes. Wait and try again. This configuration affects only the responses received by clients, not the cache behavior of POPs, so no refresh or prefetch is required (prefetch does not change the response headers of already cached resources).

• The response headers of the origin server conflict with the CDN configuration: If the origin server also returns CORS response headers, the headers may override each other. We recommend that you use consistent CORS configurations on the origin server and CDN, or set Allow Duplicate to No in Modify outbound response headers so that the value configured on CDN overrides the value returned by the origin server.

• The browser cached the previous response: Clear the browser cache or use private browsing mode to test.

• The wildcard domain configuration is not supported: After you enable CORS validation, you can configure only a single wildcard domain name, or multiple exact domain names separated by commas. Separating multiple wildcard domain names with commas is not supported.

• The Access-Control-Allow-Origin value does not match the request Origin: If the browser reports "The 'Access-Control-Allow-Origin' header has a value that is not equal to the supplied origin", the returned allowed origin does not match the actual request origin. You can resolve this in the following ways:

  • In Modify outbound response headers, reconfigure Access-Control-Allow-Origin and set Allow Duplicate to No so that the new value overrides the previous value returned by the origin server.

  • If your business allows, configure this response header to dynamically return the Origin value in the request so that the allowed origin always matches the request origin. After the configuration is complete, wait about 5 minutes for it to take effect. No cache refresh is required.

For how to configure cross-origin resource sharing, see Configure cross-origin resource sharing.

• Confirm that requests pass through CDN POPs: Check whether DNS resolution retains only the CNAME record provided by CDN and whether direct resolution records for origins such as OSS are removed. If traffic goes directly to the origin server, the response headers configured on CDN do not take effect.

• Confirm that you configured an outbound rather than an inbound response header: Inbound response headers apply only to communication between the origin server and CDN POPs, and end users are not aware of them. To affect the responses that end users receive, configure Modify outbound response headers.

• Confirm whether the origin server returns the response header: CDN passes through origin response headers by default. If the origin server does not return the header, CDN does not return it either. To force the response header to be included regardless of whether the origin server returns it, select the Add operation in Modify outbound response headers.

• If Content-Type does not take effect, check the metadata on the origin server: If the origin server (such as OSS) does not specify the correct Content-Type when a file is uploaded, the metadata obtained during origin fetch does not match your expectation. Check the Content-Type setting used when the file was uploaded.

• Confirm that you have waited for the configuration to take effect: Changes to the outbound response header configuration usually take effect within 5 minutes, and affect only the responses received by clients, not the cache behavior of POPs, so no refresh or prefetch is required (prefetch does not change the response headers of already cached resources).

For how to configure outbound response headers and the parameter descriptions, see Modify outbound response headers.

Cause: The Content-Type response header returned by the origin server does not correctly specify the character encoding, and the client parses the content with the wrong encoding, which causes the page to be garbled.

Solution 1 (recommended, fix at the source): Modify the origin server configuration to make sure that the Content-Type contains the correct character encoding declaration when HTML is returned.

Solution 2 (rewrite on the CDN side):

1. Log on to the CDN console. On the Domain Names page, find the target domain name and click Manage.

2. In Modify incoming response headers, add a rule to rewrite the Content-Type of the matched path to text/html; charset=utf-8.

3. After the configuration is complete, use Refresh and prefetch to refresh the cached resources under that path so that POPs cache them again with the correct type.

You can configure the Content-Disposition response header by using the Modify outbound response headers feature to control the download or preview behavior of videos: if it is set to attachment; filename='video.mp4', a download is triggered when a user accesses the resource; if it is set to inline, the resource is previewed directly in the browser.

If the configuration does not take effect, check the following items:

1. The matching condition of the rule engine: Make sure that the matching condition of the rule targets the URI path (for example, contains /video-origin/20260414) instead of only matching the query string. The rule engine determines whether the configuration takes effect by identifying the path information in the user request.

2. The POP cached the previous response header: Content-Disposition directly affects browser behavior. If the configuration does not take effect 5 minutes after it is saved, first rule out the local browser cache (retry in private browsing mode) and confirm that the rule status is Success.

Cause: When the origin server first returns the JavaScript file, the Content-Type response header is incorrectly set to text/html. After CDN caches the wrong type, the browser parses the JavaScript file as text/html, which causes garbled display or execution errors. On the second visit, the page returns to normal because the origin server corrected the Content-Type or CDN fetched the correct type from the origin server again.

Solution:

1. In Modify incoming response headers in the CDN console, add a rule to match the JavaScript file path (such as *.js) and forcibly replace the Content-Type with application/javascript.

2. After the configuration is complete, use Refresh and prefetch to refresh the cache of the JavaScript file so that the new rule takes effect immediately.

Cause: The length of the file cached on the POP does not match the actual content on the origin server, or the origin server returned an abnormal Content-Length response header. This most commonly occurs when the origin server updated a video file but CDN still returns the previously cached version.

Solution:

• On the Refresh and prefetch page, submit a refresh task for the video URL to clear the previous cache on POPs.

• If the origin server is OSS, you can enable the Automatic CDN cache refresh feature in the OSS console so that a CDN cache refresh is triggered automatically when a file on the origin server is updated.

• Check the stability of the origin server to make sure that it does not intermittently return an abnormal Content-Length value. You can run curl -I multiple times against the origin server directly to compare and verify.

Yes. Video players and download tools usually use range requests to load resources in segments. Each request retrieves only part of the content, and the server returns 206 Partial Content. Even when a request hits the CDN cache, the returned status code is 206, which is not an error.

Billing note: As long as a client sends a request to CDN and receives data, the traffic is counted as CDN outbound traffic regardless of whether the request hits the cache.

Optimization suggestions: Make sure that range origin fetch is enabled so that POPs can fetch and cache segments from the origin server on demand, which improves the hit ratio for subsequent segment requests. In addition, configure a proper Cache-Control header on the origin server (such as max-age=86400) to use the local browser cache and reduce duplicate requests.

Cause: Static resources such as images, CSS files, and JavaScript files hit the cache and are accelerated normally, but the homepage (the root path /) usually has no cache rule. Every request fetches the homepage from the origin server, so the loading speed depends entirely on the processing time of the origin server.

Solution: Add a cache expiration rule for the root directory of the accelerated domain name so that the homepage content is also cached on POPs:

1. On the Cache Expiration tab, add a rule, set the type to Directory, and set the address to /.

2. Set the expiration time based on the update frequency of the homepage content, for example, from 30 seconds to several minutes.

3. Adjust the rule weight so that the weight of the root directory rule is lower than that of the rules for specific paths (such as /static/) to avoid overriding the cache rules for static resources.

After the configuration takes effect, POPs return the homepage content directly instead of fetching it from the origin server for every request. For detailed configuration instructions, see Configure CDN cache expiration.

Cause: When a POP misses the cache, it forwards the client request and appends specific parameters to the request headers, such as Via and X-Forwarded-For. Some origin servers return different responses based on these parameters. For example, an origin server may check whether the request contains the Via header to identify proxy requests and handle them differently.

Troubleshooting steps:

1. Locate the header that causes the difference: First access the origin server directly and record the response. Then use curl to access the origin server with the headers that CDN appends, replacing and testing them one by one until you reproduce the inconsistent result.

2. Adjust the configuration of the origin server: Check how the origin web server processes the header and modify the logic based on your business requirements.

3. Or delete the header on the CDN side: If the header is not required by your business, you can delete it in the CDN console.

Cause: The origin server performed a same-name update on the file (the file content was modified but the file name was not changed). Before the cache expires, the CDN POP still returns the previous cache directly, so the downloaded file is inconsistent with the one on the origin server.

Solution:

1. Solution 1: Refresh the cache manually. After the origin server performs a same-name update, submit a URL refresh on the Refresh and prefetch page (suitable for a single resource and takes effect quickly) or a directory refresh (suitable for an entire directory and covers a wide range, but temporarily increases the origin fetch pressure on the origin server).

2. Solution 2: Force a refresh to bypass 304. If the file content on the origin server changed but the Last-Modified timestamp was not updated, the CDN POP receives 304 Not Modified after the conditional request (If-Modified-Since) validation, determines that the file has not changed, and does not update the cache. In this case, a normal URL refresh may not take effect. You must call the RefreshObjectCaches API and set the Force parameter to true to force fetching the complete file from the origin server.

3. Solution 3: Use versioned naming (recommended as a long-term solution). We recommend that the origin server avoid same-name updates. Instead, add a version number or a hash to the file name (such as style.v2.css or app.abc123.js), or carry a version identifier in a URL parameter (such as ?v=20260828).

4. Solution 4: Enable automatic refresh for an OSS origin. If the origin server is OSS, you can enable Automatic CDN cache refresh in the OSS console. When an object on the OSS origin is updated with the same name, the corresponding CDN URL is refreshed automatically.

When a web server returns the HTTP 404 status code, it automatically redirects to the 404 page, which indicates that the requested resource does not exist on the origin server. Common causes include: the URL generation rule changed, the file was renamed or moved, the link contains a typo, the website cannot be accessed on the requested port, or a web service extension lockdown policy or a MIME mapping policy blocked the request.

If the page that you access contains multiple resources and only some of them are inaccessible, the page does not redirect to the 404 page as a whole. For how to configure custom error pages, see Configure custom error pages.

When you configure a custom error page for the 403 status code, configuring the redirect link directly in the error page settings may cause a domain redirect or a redirect loop. Use the following method instead:

1. Configure the redirect by using the Access URL Rewrite feature instead of setting a redirect link in the custom error page.

2. Set the path to rewrite to / and point the target path to the correct static 403 page, for example, /error/403.html.