Handle rule issues

The rules analyzer runs continuously while you author and flags problems before they reach the Gateway. This page translates each warning into "here's why it matters" and "here's what to change."

How the analyzer thinks

Every cache rule is a (conditions, actions, priority) triple. The analyzer walks the full rule list and asks three questions:

• Will this rule ever match? (Reachability.)
• Does any earlier rule already match the same traffic? (Shadowing.)
• Is the freshness story complete? (Invalidation linkage.)

Most warnings reduce to one of those three questions. The sections below walk each one.

Shadowed rule

What it means. An earlier rule (lower priority number) matches every query the flagged rule would match — and because rules evaluate in priority order, the flagged rule never gets a chance.

Why it matters. Shadowed rules are dead code in disguise. The author thought they were tightening behavior; in practice the higher-priority rule controls everything.

What to do. Either reorder so the more specific rule runs first, or delete the redundant one. Look for cases where you wrote a per-schema rule and later layered a per-table rule on top without bumping its priority above the schema rule.

Unreachable condition

What it means. One of the conditions on a rule can never be true given the others. Common culprits: statementType = SELECT AND statementType = INSERT, or two range conditions whose intervals don't overlap.

What to do. Inspect the conditions for contradictions. If you meant "either of these," switch the rule's mode from all to either. If you meant both, one of the conditions is wrong.

Missing invalidation linkage

What it means. A cache rule with a TTL longer than a threshold has no invalidation rule pointing at it. That's not always wrong, but it's usually the warning sign of a stale-data incident waiting to happen.

What to do. Either author the invalidation rule alongside it (see Invalidation strategies) or drop the TTL. If you genuinely want a write-blind cache, dismiss the warning with a comment naming why — the dismissal becomes part of the audit trail.

Priority collision

What it means. Two rules share the same priority number and overlap on the queries they match. The Gateway picks one deterministically, but the choice isn't meaningful from the author's perspective.

What to do. Assign distinct priorities. The rules workshop renumbers in increments of 10 by default so you have room to insert later — keep that habit.

Identity in the cache key, no isolation in the actions

What it means. A rule against a schema with sensitive data omits userId from the cache key elements. This is the analyzer's hardest-hitting warning and the one closest to a security incident.

What to do. Add userId to the cache key elements, or refuse to cache the schema entirely with a zero-TTL rule at higher priority. See the per-user isolation recipe for the right shape.

Conflict with a zero-TTL guardrail

What it means. A zero-TTL rule and a cache-with-TTL rule both match the same traffic, but their priorities are ambiguous. The Gateway honors priority order — the lower-numbered priority wins — but if the zero-TTL rule wasn't deliberately set to win, that's a problem.

What to do. Push zero-TTL guardrails to priority 1, with a description naming what they guard. Other rules sort below.

Invalidation rule targets nothing

What it means. A DML rule's invalidateRules array names cache rule IDs, but one or more of those IDs no longer exists — usually because the cache rule got renamed or deleted. The DML rule still matches its writes but doesn't invalidate anything.

What to do. Update the DML rule's invalidateRules array with current IDs, or delete the DML rule if its purpose is gone.

When to ignore a warning

Most warnings are real. A few are intentional:

• You're deliberately writing a fallback rule at high priority number that you expect to be shadowed by anything more specific. That's a fallback, not dead code.
• You're caching data that legitimately doesn't have an invalidation story (purely append-only reference data, for example). Dismiss the warning with the reason as a comment.

Dismissed warnings stay dismissed across rule edits as long as the underlying rule is unchanged. Edit the rule and the warning comes back — that's intentional, so the team has to re-decide whenever the situation changes.

Where to go next

• Cache rule cookbook — recipes that won't trip the common warnings.
• Invalidation strategies — pair every long-TTL cache rule with the right invalidation source.
• Investigate a statement — when a query you expected to hit cache doesn't, drill into why.