Skip to content

Error Codes cache

github-actions[bot] edited this page Nov 16, 2026 · 2 revisions

Error codes: @ultimat3/cache

Part of Error codes: every code @ultimat3/cache registers. x errors explain <CODE> --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) cache.<tier>.jitterFraction at 1 or above, negative, or not finite. 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. 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. 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] x manifest to regenerate the tag graph, then fix the tag
X_CACHE_TOO_LARGE one entry exceeds the tier's byte budget caching a whole row set raise cache.<tier>.maxBytes, 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

Clone this wiki locally