Support

Find answers, guides, and tutorials to supercharge your content delivery.

CDN Troubleshooting Guide

Updated on February 24, 2022

This guide provides a list of troubleshooting suggestions for issues that you may experience when configuring a CDN.

Troubleshooting tools

Are assets being cached on the KeyCDN edge servers?

There are six different cache statuses that may be returned by the KeyCDN edge servers. These include HIT, MISS, EXPIRED, REVALIDATED, UPDATING, and STALE. To learn more about what each cache status mean, read our What cache statuses are there?.

In order to check the cache status of a particular asset, you can run a curl command and check the X-Cache response header.

curl -I https://www.keycdn.com
HTTP/2 200
server: keycdn-engine
date: Thu, 12 Mar 2020 04:47:35 GMT
content-type: text/html
vary: Accept-Encoding
last-modified: Thu, 05 Mar 2020 11:41:26 GMT
etag: W/"5e60e566-13e3b"
expires: Thu, 19 Mar 2020 04:47:35 GMT
cache-control: max-age=604800
strict-transport-security: max-age=31536000; includeSubdomains; preload
content-security-policy: default-src 'self' 'unsafe-inline' 'unsafe-eval' https: data:
x-frame-options: SAMEORIGIN
x-xss-protection: 1; mode=block
x-content-type-options: nosniff
referrer-policy: no-referrer-when-downgrade
**x-cache: HIT**
x-edge-location: ussf
access-control-allow-origin: *

An X-Cache: HIT means that the asset was delivered by a KeyCDN edge server and is properly cached. To receive a HIT status, the resource needs to be requested at least twice from the same server in order to ensure the asset is cached.

Is your Zone Alias (CNAME) correctly configured?

Go to the KeyCDN Tools DNS Checker and verify that your Zone Alias (e.g. cdn.example.com) points to the Zone URL (e.g. example-hexid.kxcdn.com).

Are your assets loading from KeyCDN?

Go to the KeyCDN Tools HTTP Header Checker and test this with a single asset such as a CSS file. It is important that you see the following in the HTTP response headers:

  • HTTP/1.1 200 OK or HTTP/2 200
  • Server: keycdn-engine

Debugging why assets aren't delivered by the CDN

If you have just integrated a CDN in your website and notice that some assets aren't being delivered via the CDN URL this may be due to a few reasons.

  • If you plan to deliver your CDN assets using a custom URL (e.g. cdn.example.com) ensure that you have properly added the CNAME record to your DNS settings and Zone Alias in your KeyCDN dashboard. If either one of these steps are missed, your assets will not be delivered via the custom CDN URL. Use our DNS check tool to ensure your CNAME is properly configured.
  • Ensure that the proper path is being used when requesting an asset via the CDN. If you have implemented any custom rewrites, double check that these do not conflict with the correct asset path.
  • If you are using WordPress, some assets simply do not get delivered via the CDN such as the wp-emoji-release.min.js file as this always gets delivered via the origin.
  • If you are using CDN Enabler and have noticed that some asset URL aren't being rewritten, check the page source to ensure you are not using a dynamic protocol //. CDN Enabler will not rewrite these assets and therefore it is recommend to use the full protocol, either http:// or https://.
  • In some cases, resources within third party plugins are defined manually (e.g. an image to be used within a slider plugin). Ensure that once you have properly set up the CDN, you modify the image URL to point to your CDN or Zone URL.

Are the Assets not loaded correctly via HTTPS?

For HTTPS there is Shared SSL or Custom SSL available. An asset can only be loaded via Shared SSL, Let's Encrypt SSL, or Custom SSL but not two methods at the same time. This means that once you have enabled either Custom or Let's Encrypt SSL, accessing the HTTPS version of your Zone URL (e.g. https://example-hexid.kxcdn.com) will not work.

For HTTPS, a client needs to support SNI, this means that any version of Internet Explorer running on Windows XP will not work with HTTPS. In this case, please use a different browser (e.g. Firefox or Chrome) or upgrade Windows XP to at least Windows 7.

If the HTTPS connection is not setup correctly, a browser will typically show a message like this:

If you have trouble, loading the assets via HTTPS, please check the following points:

Shared SSL

  1. Ensure that Shared SSL is enabled in the KeyCDN dashboard.

Let's Encrypt

  1. Ensure that you have the Let's Encrypt SSL option enabled in the KeyCDN dashboard.
  2. If your Zone already has a Zone Alias created and you enable the Let's Encrypt option, you will need to recreate the Zone Alias in order to Let's Encrypt SSL to work. Otherwise if you haven't created a Zone Alias yet, simply enable the Let's Encrypt option first and create the Zone Alias afterwards.

Custom SSL

  1. Make sure that Custom SSL (not Shared SSL) is enabled for this Zone

  2. Verify that the Zone Alias has been setup properly (incl. the CNAME on your DNS and the Zone Alias is mapped to the right zone).

    • How to check if the CNAME on your DNS has been setup correctly? Use the KeyCDN Tools DNS Checker in order to verify your DNS globally.
    • How to verify if the Zone Alias has been setup correctly? Check a single file with KeyCDN Tools HTTP Check.
  3. Are you having issues uploading your certificate in the KeyCDN dashboard? Your private key of the certificate must match to the certificate, otherwise it won't be accepted in the dashboard. Do not use an encrypted private key (the first line of an encrypted cert normally starts with -----BEGIN ENCRYPTED PRIVATE KEY-----). Here's how you verify on the CLI if your private key matches your certificate:

    openssl x509 -noout -modulus -in certificate.crt | openssl md5
    openssl rsa -noout -modulus -in privateKey.key | openssl md5
    
  4. Check that your certificate is issued for your Zone Alias (e.g. cdn.yourdomain.com). A certificate only issued for www.yourdomain.com will not work for cdn.yourdomain.com.

    • How to check if your certificate is valid for your subdomain? Use a SSL certificate checker in order to verify if your certificate is valid for this Zone Alias.
  5. Ensure that the certificate chain is complete. If there are intermediate certs missing in the certificate chain, it's possible that some clients are not loading the content (note: chain certificates and intermediate certificates are the same).

    • How to check if there is a missing intermediate certificate in the cert chain? Go to SSLLabs and check your domain (e.g. cdn.yourdomain.com) and go to "Chain issues" which should be "none". Here is an example of a complete certificate chain.
    • Where to get missing intermediate certificates? Normally, all the needed intermediate certificates are sent along when a new certificate is ordered. If you don't have these intermediate certs, you can use our Certificate Chain Composer to automatically generate them. Additionally, you can either reissue your certificate (where you should also get new chain certificates) or you can find the needed chain certificates based on the fingerprint ID provided by SSLLabs.
  6. Check your certificate for weak keys. Your certificate should be A-graded. It's possible that a certificate will not be considered as secure anymore after a browser update.

    • How to check a certificate for weak keys? Go to SSLLabs and check the grade of your domain, also check "Weak key".
    • What should you do if your certificate has weak keys? You need to reissue your certificate. This is normally available for free in the dashboard of your SSL issuer. Please contact your SSL issuer for more details. You then need to upload the newly issues certificate in the KeyCDN dashboard.
  7. A change in the KeyCDN dashboard takes less than 5 minutes to be globally propagated. Make sure you wait a few minutes after a change.

Your website is loading slow even though you implemented a CDN?

Use one of the speed check tools above to get more insights. Verify if you're getting any error codes and resolve them first. Avoid redirects as they will cause more RTTs and therefore slow down your website. Identify assets that are obviously loading slower than others and check if the X-Cache HTTP header field shows a HIT or MISS.

A slow loading website can also be related to a slow origin server or external assets (commonly render blocking JavaScript libraries), which are loading slowly and decrease the overall load time of your website. Keep in mind that the initial HTML document is still loaded from your origin server, which means it is crucial that your server needs to be optimized as well.

We recommend reading this website performance optimization article, which highlights the most important performance tips to help further accelerate your website.

Why is my cache hit ratio low?

A number of factors can have an impact on your cache hit ratio (CHR). Please check the following points if you think the CHR is too low:

  • Query strings (QS): Each QS will create a new cache entry if query strings are not ignored. QS can be important to distinguish different versions of a file but it will cause extra cache entries if not used properly. QS can be ignored for each Zone, it will then always be cached as the same file.
  • Expire headers: By default all HTTP headers from the origin server will be honoured by KeyCDN. It's important to define meaningful expire values. Also, take note that certain expire headers define their value in minutes while others are in seconds (e.g. X-Accel-Expires is in seconds while Expire is in minutes).
  • Purge: Each purge (either a particular file or the entire Zone) will delete the content on all POPs. The file(s) will then be cached again with the first request.
  • New files: Every new file needs to be cached on each POP all around the world. This will result in one cache miss for each file and POP.
  • User generated content (long tail content): The traffic pattern will also have a significant impact on the CHR. In case of user generated content, new files need to be cached more often because of the "long tail" (which will lead to a lower CHR).
  • Not cacheable content: Not every file is cacheable. Files will be cached based on the Cache-Control header. Files with cookies cannot be cache if the cookie is not stripped away (see the feature in Zone settings).

Visit our CDN Cache Hit Ratio article for more details.

Are you getting 403 Forbidden after you enabled Zone Referrers?

First of all, keep in mind that assets which you access directly in your browser or using tools like curl do NOT have a referrer field in the HTTP request header. Requests without an HTTP referrer field are NOT allowed to access your assets if you enable any Zone Referrer for your Zone.

  1. Verify the HTTP Referer - Chrome's Developer Tools can help you with this. Open the Network panel and reload your website. Click on the asset that is having a 403 status code and analyze the headers. Does the Referer header show what you expected?

    In the example above you would be required to set www.keycdn.com as a Zone Referrer.

  2. Verify if the Zone Referrer is enforced as expected with KeyCDN Tools HTTP Header Checker. Referrer allowed example (www.demo.com is a valid referrer):

    Referrer blocked example:

How to further analyze the 4xx client errors shown in the dashboard?

Under Reporting > Usage among other useful information, the number of 4xx errors are shown. Here's an example:

There are a number of reasons causing 4xx errors. Some of them can be:

  • Browsers are sometimes requesting files by default (e.g. /favicon.ico ) even if the files don't exist and are not part of the HTML.
  • Your Secure Token has expired which will result in a 410 error for the client.
  • A bad bot is blocked on the edge server resulting in a 451 error.
  • Users can manually request files. The files might not exist.
  • Bots from search engines might crawl for content.
  • You are using Zone Referrers and therefore any referrer you haven't added to the list will receive a 403 Forbidden.
  • Your website is requesting files which don't exist but should be there. That's the case you want to avoid and you should further analyze!

If you have a relative small number of 404 errors, in most cases it's perfectly normal. Even for a correctly working website, there may not be zero 4xx errors. In the screenshot above, there are over 48 million 2xx requests and only 175 4xx requests. This ratio is absolutely normal but customers sometimes still want to investigate the 4xx client errors. Here's how the 4xx client errors can be analyzed. There are two options:

  • Take advantage of the raw logs: The raw logs can be forwarded to a host of your choice. The raw logs (e.g. all 404 requests) can then be further processed. Log forwarding can be enabled in the KeyCDN dashboard. The log format offers all the information needed.

How to verify if the filter for X-Pull is properly implemented on your origin server?

Our HTTP Header Checker tool can help you with that. Just specify the X-Pull header value and verify if you are getting the response you are expecting (e.g. 403 Forbidden). Visit our How to Use X-Pull article to learn more about configuring this feature on your origin server.

Video files such as MP4 need to download completely before playing in your player?

Make sure that the metadata is at the beginning of your MP4 video file. Tools like MetaData Mover could help you to move the metadata from the end to the beginning.

Why can't I log in to my FTP account?

Please check your FTP settings and ensure you are using your KeyCDN Subuser credentials and not your email address. If you still can't login, please send us your IP address in a support request and we'll check if your IP address has been blocked.

Why are my images being deindexed from Google Search Console?

If your images start to get deindexed from your Google Search Console account, this is likely a sitemap structure issue. Assuming you are using the Yoast SEO WordPress plugin, you may need to add the following snippet at the top of your functions.php file in order for Yoast to index your images from the CDN domain.

function wpseo_cdn_filter($uri) {
    return str_replace('https://www.yoursite.com', 'https://cdn.yoursite.com', $uri);
}

add_filter( 'wpseo_xml_sitemap_img_src', 'wpseo_cdn_filter' );

Once you've added the snippet and modified it to use your origin URL and CDN URL, save the file and go to the Yoast SEO XML Sitemap page. You will need to regenerate the sitemap in order for the changes to take affect. In order to do this, set the XML sitemap functionality to "Disabled" then Save Changes. Once this is done, set it back to Enabled and Save Changes again. Your sitemap will now use the CDN URL to reference images.

Before adding functions.php snippet:

After adding functions.php snippet:

Learn more about indexing images in SERPs by reading our CDN SEO guide.

How to fix a 301 redirect back to my origin server?

If you have KeyCDN integrated with your website, however are receiving a 301 redirect when trying to access a CDN URL (e.g. https://cdn.yourwebsite.com/path/to/your/image.jpg) there are a couple of things you can check.

  • Verify that you are using the correct origin URL for your KeyCDN Zone. Be aware that if your origin URL is using a www subdomain, this must also be entered in the origin URL. Also, double check you have entered the correct protocol (e.g. http:// or https://).
  • 301 redirects always come from the origin server, therefore double check that you don't have any special redirect rules in place that are redirecting your assets.
  • Be sure to purge your entire KeyCDN Zone once any modifications have been made to fix the 301 redirects. The edge servers cache 301 redirects therefore even though you may have solved the problem, if the Zone isn't purged you may still see a redirect occur.
KeyCDN uses cookies to make its website easier to use. Learn more