Repository navigation
Error Codes cache
github-actions[bot] edited this page Nov 16, 2026
·
2 revisions
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 |
Ultimate — v31.44.0 As of 2026-10. The full-stack framework where the primary developer is an AI agent: bunx create-ultimate myapp → Getting started · live demo. MIT licensed. What npm serves is npm view @ultimat3/core version, never this line, and this footer is the only page that stamps a version.
Repository · Issues · Changelog · llms.txt
Edits to these pages are synced from wiki/ in the repository — change the file there, not the wiki, or the next sync overwrites it.
Start
- Getting started
- Installation
- Shapes
- Bare VM
- Project layout
- Migrating an existing app
- Compared to other stacks
Tutorials
- 1 · First app
- 2 · First feature
- 3 · Auth and admin
- 4 · Jobs and realtime
- 5 · Deploy free
- 6 · Growing up
Primitives
- The eight primitives
- Building your own base
- Actions
- Entities and migrations
- Policies and authz
- Queries and live queries
- Client data
- Jobs and workflows
- Scheduled tasks
- Routes and render modes
Capabilities
- Realtime
- Caching and invalidation
- Batching and preloading
- N+1 detection
- PWA and offline
- Client navigation
- MCP and AI
- Agents
- Admin dashboard
- Scraping
- Auth
- Notify
- Storage and uploads
- Feature flags
- SEO
- Static assets
Cross-cutting
- I18n
- Theming
- UI components
- Interface rules
- Timezones and dates
- Money
- Outbound HTTP
- Resource management
- Migrations and backfills
- Testing
- CI: the gate across parallel jobs
Reference