Fastly troubleshooting

Use the following information to troubleshoot and manage the Fastly CDN module for Magento 2 in your Magento Commerce Cloud project environments. For example, you can investigate response header values and caching behavior to resolve Fastly service and performance issues.

For information about setting up and configuring Fastly, see Set up Fastly.

Locate Fastly service ID

You need the Fastly service ID to configure Fastly from the Magento Admin UI or to submit Fastly API requests for advanced Fastly configuration and troubleshooting.

If Fastly is enabled in your project environment, you can get the service ID from the Magento Admin UI. See Get Fastly credentials.

Developers and advanced VCL users can use custom VCL to retrieve the service ID using the Fastly variable req.service_id. For example, you can add the req.service_id to the custom logging directive in your VCL to capture the service ID value:

log {"syslog"} req.service_id {" my_logging_endpoint_name :: "}

You can use the same VCL for Production and Staging environments. See How to configure vcl_log.

Troubleshoot site performance, purge, and cache issues

Use the following list to identify and troubleshoot issues related to the Fastly service configuration for your Magento Commerce Cloud environment.

Store menu does not display or work—You might be using a link or temp link directly to the origin server instead of using the live site URL, or you used -H "host:URL" in a cURL command. If you bypass Fastly to the origin server, the main menu does not work and incorrect headers display that allow caching on the browser side.
Top level navigation does not work—The top level navigation relies on Edge Side Includes (ESI) processing which is enabled when you upload the default Magento Fastly VCL snippets. If the navigation is not working, upload the Fastly VCL and recheck the site.
Geo-location/GeoIP does not work— The default Magento Fastly VCL snippets append the country code to the URL. If the country code is not working, upload the Fastly VCL and recheck the site.
Pages are not caching—By default, Fastly does not cache pages with the Set-Cookies header. Magento sets cookies even on cacheable pages (TTL > 0). The default Magento Fastly VCL strips those cookies on cacheable pages. If pages are not caching, upload the Fastly VCL and recheck the site.

This issue can also occur if a page block in a template is marked uncacheable. In that case, the problem is most likely caused by a third-party module or Magento extension blocking or removing the Magento headers. To resolve the issue, see X-Cache contains only MISS, no HIT.
Purge requests are failing—Fastly returns the following error when you submit a purge request:

The purge request was not processed successfully.

This issue can be caused by either of the following issues:
- Invalid Fastly credentials in the Fastly service configuration for the Magento Commerce Cloud project environment
- Invalid code in a custom VCL snippet
To resolve the issue, see Error purging Fastly cache on Cloud in the Magento Help Center.

503 errors from Fastly

If Fastly returns 503 timeout errors, check the error logs and the 503 error page to identify the root cause.

If the timeout occurs when running bulk operations, you can extend the Fastly timeout for the Magento Admin UI.

If you receive a 503 error, check the Production or Staging environment error log and php access log to troubleshoot the issue.

To check the error logs:

Error log
```
1
/var/log/platform/<project_ID>/error.log
```
This log includes any errors from the application or PHP engine, for example memory_limit or max_execution_time exceeded errors. If you do not find any Fastly-related errors, check the PHP access log.
PHP access log
```
1
/var/log/platform/<project_ID>/php.access.log
```
Search the log for HTTP 200 responses for the URL that returned the 503 error. If you find the 200 response, it means that Magento returned the page without errors. That indicates the issue might have occurred after the interval that exceeds the first_byte_timeout value set in the Fastly service configuration.

When a 503 error occurs, Fastly returns the reason on the error and maintenance page. You might not be able to see the reason if you added code for a custom response page. To view the reason code on the default error page, you can remove the HTML code for the custom error page.

To check the Fastly 503 error page:

Log in to the Magento Admin UI.
Click Stores > Settings > Configuration > Advanced > System.
In the right pane, expand Full Page Cache.
In the Fastly Configuration section, expand Custom Synthetic Pages as the following figure shows.
Click Set HTML.
Remove the custom code. You can save it in a text program to add back later.
Click Upload to send your updates to Fastly.
Click Save Config at the top of the page.
Reopen the URL that caused the 503 error. Fastly returns an error page with the reason as shown in the following example.

Apex and subdomains already associated with a Fastly account

If the apex domain and subdomains for your Magento Commerce Cloud project are already associated with an existing Fastly account with an assigned Service ID, you cannot launch until you update your Fastly configuration:

Update the apex and subdomain configuration on the existing Fastly account. See Multiple Fastly accounts and assigned domains.
Enable and configure Fastly and complete the DNS configuration for your project environment.

Verify or debug Fastly services

You can troubleshoot performance or caching issues for a Magento Commerce Cloud site by testing site URLs and examining the header values returned in the response.

Check live site through Fastly

Use the Fastly API to check the following response headers returned from your live site: Fastly-Magento-VCL-Uploaded and X-Cache.

Fastly API requests are passed through the Fastly extension to get a response from your origin servers. If the response returns incorrect headers, test the origin servers directly.

To check the response headers:

In a terminal, use the following curl command to test your live site URL:

curl https://<live URL> -vo /dev/null -H Fastly-Debug:1

If you have not set a static route or completed the DNS configuration for the domains on your live site, use the --resolve flag, which bypasses DNS name resolution.

curl https://<live URL> -vo /dev/null -H Fastly-Debug:1 [--resolve] <live URL hostname>:443:<live IP address>

In the response, verify the headers to ensure that Fastly is working. You should see following unique headers in the response:

< Fastly-Magento-VCL-Uploaded: yes
< X-Cache: HIT, MISS

If the headers do not have the correct values, see the following information:

Check VCL upload
X-Cache contains only MISS, no HIT

Bypass Fastly to check Staging and Production sites

If the Fastly service returns incorrect headers, submit a Fastly API request directly to the origin server, bypassing the Fastly CDN service.

To check the response headers:

To get the response data, submit an API request the origin server:

Staging

curl http[s]://staging.<your domain>.c.<project ID>.ent.magento.cloud -H "Host:<URL>" -k -vo /dev/null -H Fastly-Debug:1

Production

Submit the following request to test the load balancer:

curl http[s]://<your domain>.c.<project ID>.ent.magento.cloud -H "Host:<URL>" -k -vo /dev/null -H Fastly-Debug:1

Submit the following request to test a direct Origin node:

curl http[s]:<your domain>.{1|2|3}.<project ID>.ent.magento.cloud -H "Host:<URL>" -k -vo /dev/null -H Fastly-Debug:1

For example, if you have a public URL www.mymagento.biz, enter a command similar to the following to test the production site:

curl -k https://www.mymagento.biz.c.sv7gVom4qrpek.ent.magento.cloud -H 'Host: www.mymagento.biz' -vo /dev/null -H Fastly-Debug:1

If you have not completed the DNS configuration for the public hostname, remove the "Host:<URL>" option as shown in the following example:

curl -k https://www.mymagento.biz.c.sv7gVom4qrpek.ent.magento.cloud -vo /dev/null -H Fastly-Debug:1

In the response, check for errors in the cache HIT and MISS headers.

Check cache HIT and MISS response headers

Verify that the returned response contains the following information:

Includes the X-Magento-Tags header
The value of the Fastly-Module-Enabled header is either Yes or the version number of the Fastly for CDN Magento 2 module installed in the project environment
Cache-Control: max-age is greater than 0
Pragma setting is cache

The following excerpt from the cURL command output shows the correct values for the Pragma, X-Magento-Tags, and Fastly-Module-Enabled headers:

* STATE: INIT => CONNECT handle 0x600057800; line 1402 (connection #-5000)
* Rebuilt URL to: https://www.mymagento.biz.c.sv7gVom4qrpek.ent.magento.cloud/
* Added connection 0. The cache now contains 1 members
* Trying 192.0.2.31...
* STATE: CONNECT => WAITCONNECT handle 0x600057800; line 1455 (connection #0)

% Total    % Received % Xferd  Average Speed   Time    Time     Time  Current
                                 Dload  Upload   Total   Spent    Left  Speed
0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0* Connected to www.mymagento.biz.c.sv7gVom4qrpek.ent.magento.cloud (54.229.163.31) port 443 (#0)

* STATE: WAITCONNECT => SENDPROTOCONNECT handle 0x600057800; line 1562 (connection #0)
  0     0    0     0    0     0      0      0 --:--:-- --:--:-- --:--:--     0* ALPN, offering h2

... portion omitted for brevity ...

< Set-Cookie: mage-messages=%5B%5D; expires=Wed, 22-Nov-2017 17:39:58 GMT; Max-Age=31536000; path=/
< Pragma: cache
< Expires: Wed, 23 Nov 2016 17:39:56 GMT
< Cache-Control: max-age=86400, public, s-maxage=86400, stale-if-error=5, stale-while-revalidate=5
< X-Magento-Tags: cb_welcome_popup store cb cb_store_info_mobile cb_header_promotional_bar cb_store_info cb_discount-promo-bar cpg_2 cb_83 cb_81 cb_84 cb_85 cb_86 cb_87 cb_88 cb_89 p5646 catalog_product p5915 p6040 p6197 p6227 p7095 p6109 p6122 p6331 p7592 p7651 p7690
< Fastly-Module-Enabled: yes
< Strict-Transport-Security: max-age=31536000
    < Content-Security-Policy: upgrade-insecure-requests
    < X-Content-Type-Options: nosniff
    < X-XSS-Protection: 1; mode=block
    < X-Frame-Options: SAMEORIGIN
    < X-Platform-Server: i-dff64b52
    <
    * STATE: PERFORM => DONE handle 0x600057800; line 1955 (connection #0)
    * multi_done
      0     0    0     0    0     0      0      0 --:--:--  0:00:02 --:--:--     0
    * Connection #0 to host www.mymagento.biz.c.sv7gVom4qrpek.ent.magento.cloud left intact

For detailed information on hits and misses, see Understanding cache HIT and MISS headers with shielded services in the Fastly documentation.

Resolve errors found in response headers

This section provides suggestions for resolving errors returned when checking response headers using the Fastly API.

Fastly module is not enabled

If the Fastly module is not enabled (Fastly-Module-Enabled: no) or if the header is missing, use SSH to log in to the project. Then, run the following command to check the module status.

php bin/magento module:status Fastly_Cdn

Based on the status returned, use the following instructions to update the Fastly configuration.

Module does not exist—If the module does not exist install and configure the Fastly CDN Module for Magento 2 in an Integration branch. After installation completes, enable and configure the module. See Set up Fastly.
Module is disabled—If the Fastly module is disabled, update the environment configuration on an Integration branch in your local environment to enable it. Then, push the changes to Staging and Production. See Manage extensions.

If you use Configuration Management, check the Fastly CDN module status in the app/etc/config.php configuration file before you push changes to the Production or Staging environment.

If the module is not enabled (Fastly_CDN => 0) in the config.php file, delete the file and run the following command to update config.php with the latest configuration settings.
```
1
bin/magento magento-cloud:scd-dump
```

Fastly VCL has not been uploaded

If the Fastly VCL has not been uploaded (Fastly-Magento-VCL-Uploaded: false), use the Upload VCL option in the Magento Admin UI to upload it. See Upload Fastly VCL snippets.

X-Cache contains only MISS, no HIT

If the X-Cache header contains HIT (HIT, HIT or HIT, MISS), it indicates that Fastly returns the cached content successfully.

If the X-Cache header is MISS, MISS and does not contain HIT, run the curl command again to make sure the page was not recently purged from the cache.

If you get the same result, use the curl commands and verify the response headers:

Pragma is cache
X-Magento-Tags exists
Cache-Control: max-age is greater than 0

If the issue persists, another extension is likely resetting these headers. Repeat the following procedure in the Staging environment, disabling all extensions and re-enabling each one to determine which extension is resetting the headers. After you identify the extension causing the problem, you must disable it in the Production environment.

Log in to the Magento Admin UI.
Navigate to Stores > Settings > Configuration > Advanced > Advanced.
In the Disable Modules Output section in the right pane, locate and disable all of your extensions.
Click Save Config.
Click System > Tools > Cache Management.
Click Flush Magento Cache.
Complete the following steps for each extension potentially causing issues with Fastly headers:
- Enable one extension at a time, save the configuration, and flush the Magento cache.
- Run the curl commands to verify the response headers.
Repeat this process for each extension. If the Fastly response headers no longer display, you have identified the extension causing issues with Fastly.

After you identify the extension that is resetting Fastly headers, contact the extension developer for additional assistance. We cannot provide fixes or updates to make third-party extensions work with Fastly caching.

Rollback Fastly configuration changes

If custom VCL snippet updates or other Fastly configuration changes cause a Magento Commerce Cloud site to break or return errors, use the Fastly API activate command to rollback to an earlier VCL version. You cannot rollback the VCL version from the Magento Admin UI.

To rollback the VCL version:

To get a list of the available VCL versions for a service, run the following command

curl -H "Fastly-Key: <FASTLY_API_TOKEN>" https://api.fastly.com/service/<FASTLY_SERVICE_ID>/version/

Run the following command to change the active VCL version to a specified version.

curl -H "Fastly-Key: <FASTLY_API_TOKEN>" -H 'Content-Type: application/json' -H "Accept: application/json" -X PUT https://api.fastly.com/service/<FASTLY_SERVICE_ID>/version/<Version #>/activate

For details about using the Fastly API to review and manage VCL, see Manage VCL using the API.

Dec 21st, 2019

Edit this page on GitHub

Give us feedback