From 1208623c109c0fe6649626cb4ae253565c71afd2 Mon Sep 17 00:00:00 2001 From: Rowena Date: Wed, 5 Nov 2025 17:57:10 +0100 Subject: [PATCH 1/4] fix(es): add cache troubleshooting --- .../edge-services/how-to/configure-cache.mdx | 6 ++- .../troubleshooting/cache-problems.mdx | 43 +++++++++++++++++++ pages/edge-services/troubleshooting/index.mdx | 1 + 3 files changed, 49 insertions(+), 1 deletion(-) create mode 100644 pages/edge-services/troubleshooting/cache-problems.mdx diff --git a/pages/edge-services/how-to/configure-cache.mdx b/pages/edge-services/how-to/configure-cache.mdx index a795f12b89..de2af82442 100644 --- a/pages/edge-services/how-to/configure-cache.mdx +++ b/pages/edge-services/how-to/configure-cache.mdx @@ -121,4 +121,8 @@ For Object Storage bucket origins, the following example call to the S3 API upda 3. Click **Disable cache**. - Your cache is purged and disabled. Edge Services will now serve content by fetching it from your origin (Object Storage bucket or Load Balancer) directly. If you reenable your cache at a later point, you will begin with an empty cache. \ No newline at end of file + Your cache is purged and disabled. Edge Services will now serve content by fetching it from your origin (Object Storage bucket or Load Balancer) directly. If you reenable your cache at a later point, you will begin with an empty cache. + +## Troubleshooting cache problems + +See our [dedicated documentation](/edge-services/troubleshooting/cache-problems/) on resolving unexpected caching behavior with Edge Services. \ No newline at end of file diff --git a/pages/edge-services/troubleshooting/cache-problems.mdx b/pages/edge-services/troubleshooting/cache-problems.mdx new file mode 100644 index 0000000000..e870369372 --- /dev/null +++ b/pages/edge-services/troubleshooting/cache-problems.mdx @@ -0,0 +1,43 @@ +--- +title: I am experiencing problems with my Edge Services cache +description: Troubleshoot issues that may arise with caching on your Edge Services pipeline. +tags: edge-services cache cookies load-balancer +dates: + validation: 2025-11-05 + posted: 2025-11-05 +--- + +You may experience unexpected behavior with caching on your Edge Services pipeline. + +This page helps you resolve common problems. + +## Some assets are not being correctly cached by Edge Services. + +You may find that even though your application includes proper cache headers (e.g., `Cache-Control: max-age=...`) and is configured behind a Load Balancer with an Edge Services pipeline, static assets like images are not being cached. This can result in repeated `X-Cache: miss` responses, occasional `502` errors, and a weak cache hit:miss ratio, despite the assets being successfully served. + +### Cause + +The issue often stems from unintended cache bypasses caused by cookies in client requests. For security reasons, Edge Services blocks caching for requests with cookies. This means the cache server bypasses the origin's Cache-control header when the client is using cookies for image requests, for example. + +### Solutions + +Use the [Edge Services API](https://www.scaleway.com/en/developers/api/edge-services/#path-cache-stages-create-cache-stage) to override the default behavior by setting `include_cookies` to `true` in your cache stage. + +This tells Edge Services to cache responses even if cookies are present in the request. + +You can verify cache behavior by using `curl -X GET -I` to test as follows: + +``` +curl -X GET -I "https://your-edge-service.com/asset.jpg" +``` + +Check the X-Cache header in the response: + +- `X-Cache: hit-fresh`: the cache is working. +- `X-Cache: miss`: the cache was bypassed. + + +Be cautious when using `curl` to test. `curl -I` uses the HEAD method by default, which can mislead you during troubleshooting. Use `curl -X GET -I` for more accurate testing. + + +Use a cookie-free subdomain for static assets. This prevents cookies from being sent with requests for images, CSS, or JS. \ No newline at end of file diff --git a/pages/edge-services/troubleshooting/index.mdx b/pages/edge-services/troubleshooting/index.mdx index 66b5c816de..ceb15a8c6e 100644 --- a/pages/edge-services/troubleshooting/index.mdx +++ b/pages/edge-services/troubleshooting/index.mdx @@ -61,4 +61,5 @@ productIcon: EdgeServicesProductIcon - [I am experiencing problems with my Edge Services certificate](/edge-services/troubleshooting/certificate-errors) - [I am experiencing problems with my Edge Services CNAME record](/edge-services/troubleshooting/cname-errors) + - [I am experiencing problems with my Edge Services cache](/edge-services/troubleshooting/cache-problems/) From 595ede0240b12bf2186d0d8e749766c9bcb0546f Mon Sep 17 00:00:00 2001 From: Rowena Date: Thu, 6 Nov 2025 10:16:11 +0100 Subject: [PATCH 2/4] fix(es): review comments --- .../edge-services/troubleshooting/cache-problems.mdx | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/pages/edge-services/troubleshooting/cache-problems.mdx b/pages/edge-services/troubleshooting/cache-problems.mdx index e870369372..a3bb93cbca 100644 --- a/pages/edge-services/troubleshooting/cache-problems.mdx +++ b/pages/edge-services/troubleshooting/cache-problems.mdx @@ -11,6 +11,10 @@ You may experience unexpected behavior with caching on your Edge Services pipeli This page helps you resolve common problems. + +Before diving into this troubleshooting guide, ensure you are correctly using `curl` for your testing. `curl -I` uses the HEAD method by default, which does not always trigger the same logic as a real `GET` request. This can mislead you during cache tests, as cache checks might be skipped entirely, and responses main contain different headers. Use `curl -X GET -I` for more better testing and accurate `X-Cache` header information in responses. + + ## Some assets are not being correctly cached by Edge Services. You may find that even though your application includes proper cache headers (e.g., `Cache-Control: max-age=...`) and is configured behind a Load Balancer with an Edge Services pipeline, static assets like images are not being cached. This can result in repeated `X-Cache: miss` responses, occasional `502` errors, and a weak cache hit:miss ratio, despite the assets being successfully served. @@ -36,8 +40,8 @@ Check the X-Cache header in the response: - `X-Cache: hit-fresh`: the cache is working. - `X-Cache: miss`: the cache was bypassed. - -Be cautious when using `curl` to test. `curl -I` uses the HEAD method by default, which can mislead you during troubleshooting. Use `curl -X GET -I` for more accurate testing. - +Use a cookie-free subdomain for static assets. This prevents cookies from being sent with requests for images, CSS, or JS. -Use a cookie-free subdomain for static assets. This prevents cookies from being sent with requests for images, CSS, or JS. \ No newline at end of file + +If your cookies contain authentication data, be cautious when enabling caching with cookies. Without proper `Cache-Control` headers, sensitive content may be cached and exposed to other users. Evaluate security risks before overriding the default behavior. + \ No newline at end of file From 2aac619f9079a8f93a4e5091643888602b541210 Mon Sep 17 00:00:00 2001 From: Rowena Jones <36301604+RoRoJ@users.noreply.github.com> Date: Thu, 6 Nov 2025 10:20:58 +0100 Subject: [PATCH 3/4] Update pages/edge-services/troubleshooting/cache-problems.mdx --- pages/edge-services/troubleshooting/cache-problems.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/edge-services/troubleshooting/cache-problems.mdx b/pages/edge-services/troubleshooting/cache-problems.mdx index a3bb93cbca..6ab99d508e 100644 --- a/pages/edge-services/troubleshooting/cache-problems.mdx +++ b/pages/edge-services/troubleshooting/cache-problems.mdx @@ -12,7 +12,7 @@ You may experience unexpected behavior with caching on your Edge Services pipeli This page helps you resolve common problems. -Before diving into this troubleshooting guide, ensure you are correctly using `curl` for your testing. `curl -I` uses the HEAD method by default, which does not always trigger the same logic as a real `GET` request. This can mislead you during cache tests, as cache checks might be skipped entirely, and responses main contain different headers. Use `curl -X GET -I` for more better testing and accurate `X-Cache` header information in responses. +Before diving into this troubleshooting guide, ensure you are correctly using `curl` for your testing. `curl -I` uses the `HEAD` method by default, which does not always trigger the same logic as a real `GET` request. This can mislead you during cache tests, as cache checks might be skipped entirely, and responses may contain different headers. Use `curl -X GET -I` for better testing and more accurate `X-Cache` header information in responses. ## Some assets are not being correctly cached by Edge Services. From cb765cc448a0d957771e9a218c947d5178ad4dc8 Mon Sep 17 00:00:00 2001 From: Rowena Jones <36301604+RoRoJ@users.noreply.github.com> Date: Thu, 6 Nov 2025 14:37:41 +0100 Subject: [PATCH 4/4] Update pages/edge-services/troubleshooting/cache-problems.mdx --- pages/edge-services/troubleshooting/cache-problems.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pages/edge-services/troubleshooting/cache-problems.mdx b/pages/edge-services/troubleshooting/cache-problems.mdx index 6ab99d508e..19030fd3e6 100644 --- a/pages/edge-services/troubleshooting/cache-problems.mdx +++ b/pages/edge-services/troubleshooting/cache-problems.mdx @@ -17,7 +17,7 @@ Before diving into this troubleshooting guide, ensure you are correctly using `c ## Some assets are not being correctly cached by Edge Services. -You may find that even though your application includes proper cache headers (e.g., `Cache-Control: max-age=...`) and is configured behind a Load Balancer with an Edge Services pipeline, static assets like images are not being cached. This can result in repeated `X-Cache: miss` responses, occasional `502` errors, and a weak cache hit:miss ratio, despite the assets being successfully served. +You may find that even though your application includes proper cache headers (e.g., `Cache-Control: max-age=...`) and is configured behind a Load Balancer with an Edge Services pipeline where caching is activated, static assets like images are not being cached. This can result in repeated `X-Cache: miss` responses, occasional `502` errors, and a weak cache hit:miss ratio, despite the assets being successfully served. ### Cause