strapi-community/plugin-rest-cache/diagnose-rest-cache

Diagnosing REST Cache

Work through this in order. Do not guess at configuration changes before establishing which of the failure modes is happening — they look identical from the outside and have completely different causes.

Step 1: get the X-Cache header

This single header identifies the problem in most cases. It is off by default.

// ./config/plugins.js
strategy: {
  enableXCacheHeaders: true,
}

Restart Strapi, then request the failing route twice with curl — not a browser:

curl -sI http://localhost:1337/api/articles | grep -i x-cache
curl -sI http://localhost:1337/api/articles | grep -i x-cache

Then branch on what you see.

X-Cache: HITPASS

The request deliberately bypassed the cache. This is the most common false alarm.

The shipped hitpass skips any request carrying an authorization or cookie header. A browser logged into the admin panel sends a cookie on every request, so testing in a browser tab will always show HITPASS.

• Testing from a browser? Retest with curl, or a private window with no

session.

• Genuinely need authenticated traffic cached? That requires turning hitpass

off and turning on per-caller keys. Doing the first without the second makes two callers share one entry. Read https://strapi-community.github.io/plugin-rest-cache/guide/recipes/authenticated.html

X-Cache: MISS every time

The response is being refused. The plugin will not store a response that:

• is empty, or has a non-2xx status;
• is a stream (it can only be consumed once);
• sets a Set-Cookie header — replaying that would hand one caller's session

to everybody;

• says Cache-Control: no-store or private.

Check the response headers of the failing request for Set-Cookie and Cache-Control. A custom middleware or controller setting either of these is the usual cause.

No X-Cache header at all

The route is not cached — the middleware was never attached to it. This is configuration, not runtime.

1. Is the content type listed in strategy.contentTypes? Nothing is cached

until it is named.

1. Is it a custom route? Those must be listed explicitly, and path must

be the path as Strapi registered it, including the API prefix — /api/articles/slug/:slug, not /articles/slug/:slug.

1. Turn on strategy.debug: true (or run with

DEBUG=strapi:plugin-rest-cache). Routes that could not be matched are logged:

`` [WARNING] route "[GET] /articles/slug/:slug" not registered in strapi, ignoring... ``

1. If the admin panel is available, open Settings → REST Cache. The routes

listed per content type are the ones actually resolved. A route missing there did not match.

Stale content after an edit

Invalidation runs from Strapi's document service, which covers REST, GraphQL, the content manager, Content Releases and any strapi.documents() call.

• Was the content changed directly in the database? Nothing can observe

that. Purge manually.

• Otherwise check enableDocumentServiceMiddleware is on (it is by default).

With it off, the plugin only sees writes arriving on routes it knows about.

Entries expire far too late, or immediately

maxAge is milliseconds. 3600 is 3.6 seconds; 3600000 is one hour. This is the single most common configuration mistake.

One caller sees another caller's data

Stop and treat this as urgent.

It means responses that vary per caller are being cached under a key that does not identify the caller. Either hitpass was disabled without setting keys.useAuth: true, or a route returns per-user data while being treated as public.

Immediate mitigation: re-enable hitpass for that content type, and purge. Then read the authenticated-caching recipe before re-enabling.

Multiple instances behaving inconsistently

The memory provider is per-process. Two Strapi instances have two independent caches, and a purge on one does not reach the other — so one instance serves fresh content and another serves stale. Use the Redis provider. https://strapi-community.github.io/plugin-rest-cache/guide/recipes/multi-instance.html

Still stuck

Collect: plugin/Strapi/Node versions, the provider, the rest-cache config block, the X-Cache value, and the DEBUG=strapi:plugin-rest-cache output. Open an issue with the bug report form: https://github.com/strapi-community/plugin-rest-cache/issues/new/choose