CDN Troubleshooting Guide

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

CDN Troubleshooting Guide Index

Troubleshooting Tools

Are assets being cached on the KeyCDN edge servers?

There are 5 different cache statuses that may be returned by the KeyCDN edge servers. These include HIT, MISS, EXPIRED, REVALIDATE, and UPDATING.

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://cdn.keycdn.com/img/cdn-fast.svg
HTTP/1.1 200 OK
Server: keycdn-engine
Date: Mon, 15 Feb 2016 14:05:08 GMT
Content-Type: image/svg+xml
Content-Length: 1593
Connection: keep-alive
Vary: Accept-Encoding
Last-Modified: Thu, 16 Apr 2015 10:26:33 GMT
ETag: "552f8e59-639"
Expires: Mon, 22 Feb 2016 14:05:08 GMT
Cache-Control: max-age=604800
Strict-Transport-Security: max-age=31536000; includeSubdomains; preload
Link: <https://www.keycdn.com/img/cdn-fast.svg>; rel="canonical"
X-Cache: HIT
X-Edge-Location: usch
Access-Control-Allow-Origin: *
Accept-Ranges: bytes

An X-Cache: HIT means that the asset was delivered via 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. To learn more about what the other cache statuses mean, read our What cache statuses are there? answer in the technical FAQ.

Is your Zonealias (CNAME) correctly configured?

Go to KeyCDNs DNS Check and verify if your Zonealias points to the CDN URL.
Verify CDN DNS settings

Are your assets loading from KeyCDN?

Go to KeyCDNs DNS Check and test this with a single asset such as a CSS file. It is important that you see the following in the HTTP response header:

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

CDN header

Debugging why assets aren’t delivered via the CDN

If you have just integrated a CDN in your site 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.yourwebsite.com) ensure that you have properly added the CNAME record to your DNS settings and Zonealias 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’s 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://lorem-1c6b.kxcdn.com) will not work.

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

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

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 zonealias created and you enable the Let’s Encrypt option, you will need to re-create the zonealias in order to Let’s Encrypt SSL to work. Otherwise if you haven’t created a zonealias yet, simply enable the Let’s Encrypt option first and create the zonealias 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 Check 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 percentage low?

A number of factors can have an impact on your cache hit percentage (CHP). Please check the following points if you think the CHP 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 CHP. 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 CHP).
  • 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 blog post CDN Cache Hit Percentage for more details.

Are you getting 403 Forbidden after you enabled Zonereferrers?

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 a HTTP referrer field are NOT allowed to access your assets if you enable any zonereferrer for your zone.

  1. Verify the HTTP Referrer
    Chrome’s Developer Tools could help you with this. Open the Network tab and reload your website. Click on the asset that is having a 403 status code and analyze the headers. Does the “Referer” show what you expected?referrer header field In the example above you would be required to set www.keycdn.com as a zonereferrer for the zone demo.
  2. Verify if the zonereferrer is enforced as expected with KeyCDN Tools HTTP Check
    Referrer allowed example (www.demo.com is a valid referrer):cdn referrer allowedReferrer blocked example:cdn referrer blocked

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

Under “Reporting” –> “Analytics” among other useful information, the number of 4xx errors are shown. Here’s an example:KeyCDN-Dashboard-Reporting

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 404s, in most cases it’s perfectly normal. Even for a correctly working websites, there might not be zero 4xx errors. In the screen shot above, there are over 48 million 2xx request 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:

  • Analyze the Real-Time Logs as they are happening: Under “Reporting” –> “Real-Time Logs”, the 4xx request can be filtered. Add the filter criteria and click on the “play” symbol: KeyCDN-Real-Time-LogsThe 4xx errors will show up as they’re happening.
  • 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?

KeyCDN Tools HTTP Check could help you with that. Just specify the X-Pull form field and verify if you are getting the response you are expecting (e.g. 405 error for Nginx users and Forbidden for Apache users).
x-pull check

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 login to my FTP account?

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

Why are my images being de-indexed from Google Search Console?

If your images start to get de-indexed 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:

yoast sitemap origin domain

After adding functions.php snippet:

yoast sitemap cdn domain

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. 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 (i.e. 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.