Troubleshooting

If you hit something not on this list, open an issue with reproduction steps.

Setup and routing

Static output detected, so embedded CMS middleware and routes were skipped

You have output: 'static' (or didn’t set output). The integration needs server output to inject middleware and API routes.

Fix:

astro.config.mjs

export default defineConfig({
  output: 'server',  // or 'hybrid' with prerendering off on /admin and /api/cms
  integrations: [caret()],
});

404 on /admin

The integration didn’t inject routes. Causes:

• output: 'static' (see above)
• enableAdmin: false in caret() config
• Your host’s adapter is intercepting /admin before Astro routes (rare — check middleware)

Check the build logs for [caretcms] core loaded ... — it logs the resolved mountPath and enableAdmin flag.

404 on /api/cms/...

Same root causes as above, plus: apiBasePath is set to something else — every API route hangs off your configured base path.

Admin shows but click-to-edit doesn't appear

Check, in order:

1. Are you logged in? Visit /admin and confirm — the editor only loads when GET /api/cms/auth/session returns authenticated: true.
2. Does the page have a data-caret attribute somewhere? The editor bootstrap is a no-op on pages that don’t.
3. Are dev-tools blocking the editor JS? Look in Network for /__caret/editor.js — should be 200.
4. Is enableInlineEditor: false set anywhere? Disables the bootstrap.

Authentication

401 Unauthorized on save

Session expired (12h TTL) or never logged in. Reload /admin and log in again.

If it keeps happening within seconds:

• Cookie SameSite issues — confirm you’re on the same origin as the API
• Behind a proxy that strips cookies — check Set-Cookie lands in the browser

403 Forbidden with `Missing required request header`

You’re calling a mutating route without x-caret-request: 1. Either:

• You’re using a custom client — add the header
• You’re testing from cURL — add -H 'x-caret-request: 1'
• You’re using the shipped editor — file a bug, this should be automatic

See Authentication & Security → CSRF defense.

Login accepts the password but session check immediately fails

The session secret changed between the login request and the next request. Causes:

• CARET_SESSION_SECRET not set in production — fallback is unstable across redeploys
• Multi-instance deploy where each instance has a different secret
• You rotated the secret deliberately — re-login

Fix: set CARET_SESSION_SECRET to a stable value across all instances.

Login screen forever returns "incorrect password"

• Whitespace in the env var (trailing newline from a copy-paste)
• Two passwords set: CARET_EDIT_PASSWORD and the legacy EDIT_PASSWORD — the prefixed one wins
• Wrong env file loaded (check with node -e "console.log(process.env.CARET_EDIT_PASSWORD)" from the same shell)

Editing and Studio

409 Conflict with `Revision conflict`

Optimistic locking fired. The entry was modified between your read and your write. Reload and retry.

In the shipped editor and Studio, this is handled automatically with a toast. Custom clients should:

1. Read entry.revision along with the data
2. Pass it as expectedRevision on the mutation
3. On 409, re-read and re-apply the user’s intent

400 Bad Request on save_field

Common causes:

• Field path with __proto__, constructor.prototype, or prototype — rejected on purpose
• Field path with non-alphanumeric segments other than . and _ — rejected
• Collection name doesn’t match ^[a-z][a-z0-9_-]*$ — rejected
• Empty field or id — rejected

Check the response body for the specific issue.

Edit saves but doesn't show on the page

• Hard reload (Cmd-Shift-R) — Astro’s server response may have been cached at a CDN
• Check .caret/data/<collection>/<id>.json actually changed (filesystem adapter)
• For KV: check the value in wrangler kv:key get
• The middleware might be skipping rewriting for that route — confirm you have output: 'server' and the page is server-rendered, not prerendered

Image upload returns 200 but `src` doesn't update

• Upload provider stored the file but returned a URL the editor can’t use (CORS issue, wrong domain)
• The element has a build-time-known src overriding the field — check the field is wired through the binding
• For R2: check the bucket allows public reads or you’re using a custom domain

Storage

Edits disappear after redeploy

You’re on a host without persistent storage and using the filesystem adapter. Either:

• Add a persistent volume mounted at .caret/data/
• Switch to a DB-backed custom adapter
• Switch to Cloudflare KV if deploying to Workers

See Deployment.

Lost increments / phantom revisions

Two processes writing to the same filesystem-adapter store. The adapter serializes within a process but not across processes. Either run a single instance or use KV / a custom DB-backed adapter.

KV says "binding not found"

[caretcms] Cloud mode loaded but binding "CMS_KV" missing

Your wrangler.toml doesn’t declare CMS_KV (or whatever name you passed to cloudflareStorage({ binding: ... })).

wrangler.toml

[[kv_namespaces]]
binding = "CMS_KV"
id = "<your-kv-namespace-id>"

id comes from wrangler kv:namespace create CMS_KV.

Schema and Studio

Studio shows raw JSON instead of typed fields

The schema source is inferred and your collection has no entries yet (so nothing to infer from). Either:

• Add a starter entry that exemplifies the shape
• Register a Zod-based schema in caret({ schemas: {...} })
• Create a dynamic collection with the schema builder

Schema is registered but Studio uses inferred

Check the /api/cms/schema?collection=... response — the source field tells you which one was used. If it says inferred despite registering, the collection name in schemas doesn’t match the actual collection name (typo, case mismatch).

Dynamic collection created but not visible

After a successful create, refresh /admin/cms. The dashboard fetches /api/cms/collections-metadata once on load.

If still missing:

• Check the network response for an error
• Confirm the metadata file exists on disk (filesystem) or in KV (wrangler kv:key get meta::your-collection-id)

Performance

Studio feels slow with hundreds of entries

The default endpoints return all entries in a collection. For very large collections:

• Filter at the API layer (custom route) instead of in Studio
• Switch to a paginated DB-backed adapter
• Restructure: many smaller collections instead of one huge one

Live collections refetch on every navigation

That’s by design — live data, not cached. Add Cache-Control headers on pages where stale-by-a-few-seconds is fine, or wrap your storage adapter with a TTL cache.

Getting more help

If none of the above match:

1. Check the build/runtime logs for [caretcms] messages
2. Try the failing flow with output: 'server' and the in-memory adapter to isolate storage vs. routing
3. File an issue at github.com/web-stacked/caretcms/issues with:
   • The integration version
   • Your caret() config
   • The exact error from the network response or server log
   • Reproduction steps

API Reference Endpoint payloads, error shapes.

Authentication & Security Sessions, CSRF, secrets.

Storage Adapters Per-host storage choices.