# Error codes: `@ultimat3/cache` Part of [Error codes](Error-Codes): every code `@ultimat3/cache` registers. `x errors explain --json` prints the same row. | Code | Means | Typical cause | Fix | |---|---|---|---| | `X_CACHE_DRIVER_UNAVAILABLE` | a tier's backing store is missing | no Redis binding, or a purge driver built without `FASTLY_API_TOKEN` / `CLOUDFLARE_API_TOKEN` | provision the tier, or drop it from `app.config.ts` | | `X_CACHE_JITTER_INVALID` | a TTL jitter fraction outside `[0, 1)` | `jitterFraction` at `1` or above, negative, or not finite, refused when the tier is built. Jitter exists because 40,000 keys warmed by one rolling restart share one TTL and therefore one expiry instant, and spreading them is the only thing that stops the herd — a fraction of `1` shaves a whole lease away, a negative one **extends** it past what the caller asked for. Both are miswiring rather than preference, refused where the TTL rule already lives | `{ jitterFraction: 0.05 }` in `lruTier({ … })` / `redisTier({ … })` — a value in `[0, 1)`; `0.05` is the default, `0` disables jitter. For the rung a boot builds: `cacheTiers: [redisTier({ jitterFraction: 0.05 })]` in `apps/web/runtime.ts`. A constructor option, never an `app.config.ts` key | | `X_CACHE_LIMIT_INVALID` | a tier is given a numeric limit outside the domain its option accepts, refused at **construction**. Three domains, and the refusal names which: a **capacity** (`maxEntries`, `maxBytes`) is a whole number greater than zero; a **duration** (`defaultTtlMs`, `loadDeadlineMs`, a driver's request budget) is a whole number of milliseconds greater than zero; a **similarity floor** is a number from 0 to 1. So finite zero, a negative, a fraction and an unsafe integer are all refused too — not only `NaN` and `Infinity` | `maxEntries`, `maxBytes`, `defaultTtlMs`, `loadDeadlineMs` or a similarity floor arriving as `NaN` or `Infinity` — most often `Number(process.env.CACHE_LIMIT)` on an unset variable, which is `NaN` and is **not** nullish, so `??` does not catch it and `Math.max`/`Math.min` propagate it. The failure is the dangerous direction: a comparison against `NaN` is false for **every** entry, so the limit stops being enforced rather than being enforced wrongly — an unbounded cache that reports healthy. The cause names that mechanism **only for `NaN`**: the same refusal also catches `Infinity`, `0`, a fraction and an unsafe integer, where the bound is applied as given rather than disabled — a ceiling of `Infinity` is never exceeded and a similarity floor of `Infinity` is never met, which are opposite outcomes one sentence cannot claim at once. Raised at construction rather than on the first write, where `X_CACHE_TTL_INVALID` would have named the write instead of the config | `{ maxBytes: 10_000 }` — the fix pastes the corrected option, in the factory that read it: `lruTier()`, `redisTier()`, `memorySemanticCache()`, `fastlyPurgeDriver()`, `cloudflarePurgeDriver()`, `cacheStack()`, or the `lookup(embedding, override)` argument. For the rung a boot builds, the factory call goes in `cacheTiers` in `apps/web/runtime.ts`. None is an `app.config.ts` key. Parse an environment value first: `Number(process.env.CACHE_LIMIT)` is `NaN` when the variable is unset. `bun run finite-bounds` is the repo-wide rule | | `X_CACHE_PURGE_FAILED` | the CDN refused a purge | a wrong or unscoped API token, a zone without tag purge, a throttle, a key carrying whitespace or a comma | `meta.retryable === true` → the identical purge can land again; `false` → set the env key the `fix` names, then `x dev` | | `X_CACHE_TAG_UNKNOWN` | a tag no entity declared | typo in `invalidates: [tag.pots]`, or a new tag the app never declared. Raised only once the app has declared at least one tag | `declareTags(['pots'])` in the module that already calls it (`packages/db/src/tags.ts` in the reference app), plus `pots: true` in its `CacheTagRegistry`; for a typo, change the tag at its use to a name the cause lists | | `X_CACHE_TOO_LARGE` | one entry exceeds the tier's byte budget | caching a whole row set | `cacheTiers: [lruTier({ maxBytes: })]` or `cacheTiers: [redisTier({ maxValueBytes: })]` in `apps/web/runtime.ts`, or cache a projection | | `X_CACHE_TTL_INVALID` | a cache TTL that is not a positive number of milliseconds | `ttlMs: 0`, a negative value, `NaN` or `Infinity`. `0` used to mean "never expires" in the memory tier and "one second" in the Redis tier, so a stack holding both answered differently depending on which tier hit | pass a positive `ttlMs`, or omit it and inherit the tier's default — "do not cache" is expressed by not declaring a `cache` block | | `X_CACHE_VALUE_UNENCODABLE` | a cached value the cache codec cannot encode | a value holding a cycle, a toJSON that throws, nesting deeper than 512 levels or a bigint longer than 4096 characters, written to any tier — refused at the write, so a value is either stored and readable on every tier or not stored at all | `cache a projection of the value: plain JSON plus Date, bigint, Map and Set, with no cycles` |