Fastly troubleshooting

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

On Pro Production and Staging environments, you can use New Relic logs to view and analyze Fastly CDN and WAF log data to troubleshoot errors and performance problems.

Locate Fastly service ID

You need the Fastly service ID to configure Fastly from the Admin 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 Admin. 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.

Site performance, purge, and cache issues

Use the following list to identify and troubleshoot issues related to the Fastly service configuration for your Adobe Commerce on cloud infrastructure environment.

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 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:

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:

Apex and subdomains already associated with a Fastly account

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

Verify or debug Fastly services

You can troubleshoot performance or caching issues for an Adobe Commerce on cloud infrastructure 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 Fastly-Magento-VCL-Uploaded and X-Cache response headers returned from your live site.

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:

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

Bypass Fastly cache to check Adobe Commerce sites

If the Fastly service returns incorrect headers, you can create a VCL snippet that allows you to submit requests that bypass the Fastly cache. See Bypass Fastly cache.

After you add the VCL snippet, use cURL commands to submit requests to the origin server from the specified IP address. Then, check the responses for errors.

Check cache HIT and MISS response headers

Verify that the returned response contains the following information:

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

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.

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 Admin 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 that the page was not recently purged from the cache.

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

If the issue persists, another extension is likely resetting these headers. Repeat the following procedure in the Staging environment by 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.

To identify an extensions that resets response headers:

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

If custom VCL snippet updates or other Fastly configuration changes cause an Adobe Commerce on cloud infrastructure site to break or return errors, use the Fastly API activate command to roll back to an earlier VCL version. You cannot roll back the VCL version from the Admin.

To roll back the VCL version:

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