# Find out why WordPress pages are not cached with Grok Build

> Finding out why pages are not cached with Grok Build means asking it in your terminal to read xSpeed cache status and a benchmark through xSpeed Hub, and to judge whether a low hit ratio on a LiteSpeed server is a fault.

Page: https://xspeedcache.com/agent/grok-build/troubleshoot-cache/
Last updated: October 2026

On a LiteSpeed server the dashboard's hit ratio can look low even though pages are served fast. You ask Grok Build in the terminal: the hit ratio on shop is 14%, is caching broken? It reads get_cache_status, which includes the detected web server, then runs run_benchmark, and it can add get_health if the numbers warrant it.

The two numbers answer different questions. LiteSpeed has a static fast path in which hits never reach anything xSpeed can read, so the dashboard labels the figure as PHP-served only. The benchmark shows the cached request as a hit, at a fraction of the uncached time. Grok Build reports both: caching works, and the ratio counts only what reaches PHP. Whether you keep that trade is your choice. Grok Build asks whether the static fast path is on for the site, because the answer settles it.

Grok Build is a terminal agent, so it can also request the page and read the X-XSpeed-Cache header for you. Use a plain GET, since a HEAD request reports BYPASS on a healthy site. Grok Build starts in Ask mode, which prompts for anything a rule has not allowed, and a rule such as MCPTool(xspeedhub__get_*) lets the reads through. run_benchmark and contact_support do not start with get_, so they still prompt. If the ratio matters to you, ask for the number with its caveat attached, for example: 14%, PHP-served only, with the benchmark showing a hit. A bare figure gets quoted in a ticket or a chat message without its context, and then someone spends an afternoon looking for a fault that was never there.

## Set up Grok Build once

### 1. Put your sites in xSpeed Hub

Sign in at app.xspeedcache.com with Google or email; the Hub is free and has no site cap. Then connect each WordPress site from its own dashboard: click Connect Hub in the xSpeed Cache top bar, then Connect via xSpeed Hub. Each site needs the free xSpeed Cache plugin.

### 2. Add xSpeed Hub with grok mcp add

Run this once. Add --scope project to write the server to .grok/config.toml in the current directory instead of your user config, which is only sensible if the repo never holds a token. Grok Build handles the OAuth flow for a remote server on its own.

```bash
grok mcp add --transport http xspeedhub https://app.xspeedcache.com/xspeed/mcp
```

### 3. Sign in from the TUI

Start grok and open /mcps. Select xspeedhub and press i to authenticate, or just use a Hub tool and let the browser flow start on first use. Sign in to xSpeed Hub and approve access. There is no token to paste; Grok Build stores the credentials it receives in ~/.grok/mcp_credentials.json. If the connection fails, run grok mcp doctor xspeedhub.

```
/mcps
```

Full setup: https://xspeedcache.com/agent/grok-build/

### Before you send a prompt that changes something

Reads change nothing on your sites, though contact_support emails xSpeed support. Writes run once your connection allows them, so your client's approval prompt and a read-only connection (the token's Read-only everywhere switch, or a Viewer sign-in) are the gates that matter. Grok Build starts in Ask mode, which prompts for anything a rule has not already allowed, so a Hub write tool prompts until you say otherwise. You can allow the reads with a rule such as MCPTool(xspeedhub__get_*) in the permission section of your config, and leave the writes unmatched. Evaluation runs deny, then ask, then allow. Two other modes remove the prompt: Always-approve, from /always-approve, Ctrl+O or --always-approve, approves tool calls unless a deny rule or a hook stops them, and Auto lets a classifier approve tools it judges safe. If a Hub write must never run unprompted, add a deny rule. The Hub itself has no confirmation step.

## Prompts

- The hit ratio on shop is 14% and we run LiteSpeed. Use xSpeed Hub to check the status and run the benchmark, then tell me whether caching is broken.
- Alongside xSpeed Hub's numbers, request the shop home page twice with a plain GET and show me the X-XSpeed-Cache header each time.
- With xSpeed Hub, read get_cache_status for every site and list the web server it detected for each.

## Example session

```
You: The hit ratio on shop is 14% on our LiteSpeed host. Using xSpeed Hub, is caching broken?
  → get_cache_status(site: shop) [read-only]: page cache on, 240 cached pages, hit ratio 14% in the last 24h, web server LiteSpeed
  → run_benchmark(site: shop) [read-only]: home page: 497 ms uncached, 44 ms cached, cached request was a hit
Agent: Caching works: the home page hits and is far faster. On LiteSpeed, hits served by the static fast path never reach anything xSpeed can read, so the ratio counts only what reaches PHP. Is that path turned on for shop?
You: Yes, it is on.
Agent: Then the low ratio is a counting limit, not a fault. No change needed.
```

## How it works

1. **Start with the quick summary**: get_cache_status returns whether page caching is on, the stats (cached pages, size, hit ratio, last purge) and the web server xSpeed detected. It is a glance. If caching is off, or the hit ratio is far below what you expect, the agent moves on to the diagnostic.
2. **Run the diagnostic**: get_health is the tool for troubleshooting. It returns the environment checks with pass or warn tones (the advanced-cache.php drop-in, the WP_CACHE constant, rewrite rules, PHP and WordPress versions, caching plugin conflicts), the cache stats, 24 hourly hit and miss buckets and a 30-day hit-ratio series. The Hub tells the agent to use it, not get_cache_status, when you are troubleshooting rather than glancing.
3. **Time cached against uncached**: run_benchmark requests the home page once with the cache bypassed and once normally, after a warm-up request, and returns the timings. If the second request still is not a cache hit, the page cache is not serving the home page, and the result says so. It measures xSpeed's own response time. It does not return a Lighthouse score.
4. **Read what the checks mean**: A warn is a lead, not always a fault. A static-file rewrite warning, for example, can mean the nginx snippet is not in your server config yet, or that xSpeed could not verify it, which is not evidence the config is wrong. The agent reads the detail line and tells you which one it is.
5. **Fix it or hand it over**: If caching is simply off, toggle_cache turns it on. If another caching plugin owns the drop-in, the site refuses to enable xSpeed and says why; removing the other plugin is yours to do. If nothing explains it, contact_support emails xSpeed support with the agent's summary, after the agent has confirmed the message with you.

## Reference

| | |
| --- | --- |
| Quick check | get_cache_status (read): cache on or off, stats, detected web server |
| Diagnostic | get_health (read): environment checks, 24 hourly buckets, 30-day hit-ratio series, recent activity |
| One site per call | get_health does not accept site: "all"; call it for each site you care about |
| Benchmark | run_benchmark (read): home page only, cache bypassed against cache served, timings in milliseconds |
| Benchmark on every site | run_benchmark accepts site: "all" or a list of handles, one result per site |
| Benchmark history | get_benchmark_history reads past runs and the settings changes on the same timeline |
| Pro suggestions | get_pro_audit (read): which Pro features would help this site, from its settings and stats |
| Hit ratio scope | Counts requests that reach your server; pages answered by a CDN or Cloudflare edge are not counted |
| Support | contact_support emails xSpeed support with your account email and site list attached; classed read |
| Turning caching on | toggle_cache (write); refused by the site when another plugin owns the cache drop-in |

## Rules

- Diagnose with the read tools first. get_cache_status, get_health, run_benchmark and get_pro_audit change nothing on the site, so a read-only connection can run all of them. For clients that send the connection token, that means Read-only everywhere on; an OAuth sign-in gets the scopes the client asks for, unless the member is a Viewer.
- Do not answer a PageSpeed question with run_benchmark. It measures cached against uncached response time and returns no Lighthouse score; for a score, use the speed test or scan jobs.
- toggle_cache is a write. It runs as soon as your connection allows writes, and the Hub tells the agent to confirm the target site first. That is guidance to the agent, so your client's approval prompt is the gate that matters.
- contact_support sends a real email. The Hub tells the agent to confirm the message with you before sending, but the tool is classed read, so even a read-only connection can send one.
- The agent cannot edit your server configuration or another plugin's settings. When a check needs an nginx snippet or a conflicting plugin removed, it tells you what to do and you do it.

## Good to know with Grok Build

On a LiteSpeed host, trust the benchmark for whether pages are cached and the ratio for what reaches PHP. An agent that reads only the ratio will call a healthy site broken, so ask Grok Build to quote both. And remember that xSpeed Hub has no confirmation step of its own. Always-approve and Auto mode remove the prompt, so add a deny rule for contact_support if it must never run unprompted; deny rules still apply in Always-approve. Keep to the read tools while you investigate, or use the connection token with Read-only everywhere on, or a Viewer sign-in.

## More prompts for this job

They work in any client connected to xSpeed Hub.

- Using xSpeed Hub, why is the cache hit ratio so low on shop? Run the full health check and tell me the most likely cause.
- Using xSpeed Hub, is page caching actually working on blog? Benchmark cached against uncached and tell me if the second request was a hit.
- xSpeed Hub's get_health on docs shows a warning about the static-file rewrite. What does it mean and do I need to act?
- Use xSpeed Hub to check whether another caching plugin is conflicting with xSpeed on shop.
- Caching looks off on the staging site. Use xSpeed Hub to turn it on and tell me if the site refuses.
- Using xSpeed Hub, which Pro features would help the shop site, based on how it is set up now?
- With xSpeed Hub, compare the last few benchmark runs on blog and tell me whether my settings changes helped.

## Frequently asked questions

### Why is my hit ratio low on LiteSpeed when Grok Build says caching works?

With the static fast path on, hits are served by LiteSpeed and never reach anything xSpeed can read, so the figure counts only requests that reach PHP. The benchmark shows whether the cached request is a hit, which is the better test of whether caching works.

### Does Grok Build need write access to troubleshoot my cache?

No. Cache status, health checks and the benchmark only read, so a read-only connection is enough (the connection token with Read-only everywhere on, or a Viewer sign-in). Anything that changes the site, such as turning caching on, is a write and needs a connection that allows it.

### Why are my WordPress pages not being cached?

The common causes are that page caching is switched off, the advanced-cache.php drop-in or the WP_CACHE constant in wp-config.php is missing, another caching plugin owns the drop-in, or the pages set cookies or headers that make them uncacheable. An agent can read all of these from get_health through xSpeed Hub and tell you which one applies to your site.

### What is the difference between get_cache_status and get_health?

get_cache_status is a quick summary: whether caching is on, the stats and the detected web server. get_health is the diagnostic. It adds the environment checks with pass or warn tones, 24 hourly hit and miss buckets and a 30-day hit-ratio series. The Hub tells the agent to use get_health when you are troubleshooting.

### Does run_benchmark give me a PageSpeed score?

No. run_benchmark measures how fast your own cache answers compared with an uncached request for the home page. For a Lighthouse score, ask for a speed test or a speed scan instead.

### Can the agent check every site at once?

Only partly. run_benchmark accepts every site in one call. get_cache_status and get_health take one site per call, and get_health does not accept site: "all", so for a fleet the agent calls them site by site or you use the Hub dashboard for the rollup.

### Will troubleshooting change anything on my site?

Not with the diagnostic tools. They are read tools and change nothing. Changes only happen if the agent calls a write tool such as toggle_cache, which runs once your connection allows writes, so your AI client's approval prompt and a read-only connection (the connection token with Read-only everywhere on, or a Viewer sign-in) are the gates.

## Find out why pages are not cached with other agents

[Claude Code](https://xspeedcache.com/agent/claude-code/troubleshoot-cache/) · [Claude](https://xspeedcache.com/agent/claude/troubleshoot-cache/) · [Claude Cowork](https://xspeedcache.com/agent/claude-cowork/troubleshoot-cache/) · [ChatGPT](https://xspeedcache.com/agent/chatgpt/troubleshoot-cache/) · [Codex](https://xspeedcache.com/agent/codex/troubleshoot-cache/) · [Cursor](https://xspeedcache.com/agent/cursor/troubleshoot-cache/) · [GitHub Copilot in VS Code](https://xspeedcache.com/agent/github-copilot/troubleshoot-cache/) · [Windsurf](https://xspeedcache.com/agent/windsurf/troubleshoot-cache/) · [Gemini CLI](https://xspeedcache.com/agent/gemini-cli/troubleshoot-cache/) · [Antigravity](https://xspeedcache.com/agent/antigravity/troubleshoot-cache/) · [Zed](https://xspeedcache.com/agent/zed/troubleshoot-cache/) · [Kiro](https://xspeedcache.com/agent/kiro/troubleshoot-cache/) · [OpenCode](https://xspeedcache.com/agent/opencode/troubleshoot-cache/) · [OpenClaw](https://xspeedcache.com/agent/openclaw/troubleshoot-cache/) · [Hermes Agent](https://xspeedcache.com/agent/hermes-agent/troubleshoot-cache/) · [ChatGPT dots](https://xspeedcache.com/agent/chatgpt-dots/troubleshoot-cache/) · [Grok](https://xspeedcache.com/agent/grok/troubleshoot-cache/) · [Grok Bot](https://xspeedcache.com/agent/grok-bot/troubleshoot-cache/) · [Muse](https://xspeedcache.com/agent/muse/troubleshoot-cache/) · [Manus](https://xspeedcache.com/agent/manus/troubleshoot-cache/) · [Kimi Code](https://xspeedcache.com/agent/kimi/troubleshoot-cache/) · [Paperclip](https://xspeedcache.com/agent/paperclip/troubleshoot-cache/) · [NanoClaw](https://xspeedcache.com/agent/nanoclaw/troubleshoot-cache/)

## More with Grok Build

- [Purge the WordPress cache with Grok Build](https://xspeedcache.com/agent/grok-build/purge-cache/)
- [Scan a website for speed problems with Grok Build](https://xspeedcache.com/agent/grok-build/speed-scan/)
- [Run and track PageSpeed tests with Grok Build](https://xspeedcache.com/agent/grok-build/pagespeed-tests/)
- [Raise a WordPress site's PageSpeed score with Grok Build](https://xspeedcache.com/agent/grok-build/optimize-site/)
- [Tune WordPress cache settings with Grok Build](https://xspeedcache.com/agent/grok-build/cache-settings/)
- [Warm the WordPress cache with Grok Build](https://xspeedcache.com/agent/grok-build/preload-cache/)
- [Set up the Redis object cache with Grok Build](https://xspeedcache.com/agent/grok-build/object-cache/)
- [Manage Cloudflare caching with Grok Build](https://xspeedcache.com/agent/grok-build/cloudflare/)
- [Manage every WordPress site at once with Grok Build](https://xspeedcache.com/agent/grok-build/fleet/)

## Documentation

- How to read your cache diagnostics: https://xspeedcache.com/docs/cache-diagnostics/
- Understanding cache hits and misses: https://xspeedcache.com/docs/hits-and-misses/
- How to check your site health: https://xspeedcache.com/docs/health/
- Common problems and troubleshooting: https://xspeedcache.com/docs/common-problems-and-troubleshooting/
- How to enable Page Cache: https://xspeedcache.com/docs/page-cache/