Troubleshooting & FAQs

Diagnose common setup, routing, authentication, and database issues in CopyPatch v2 integrations.

1. Quick Diagnostic with CLI

The fastest way to test your local configuration, environment variables, and storage connection is to run the doctor command:

Terminal

# Run runtime diagnostic check
npx copypatch doctor

2. Error Codes Reference

Error Code	HTTP Status	Root Cause	Resolution
`ORIGIN_REJECTED`	`403 Forbidden`	The request's `Origin` header did not exactly match the host domain.	Ensure requests are same-origin. Remove external proxy URLs or CORS headers; access the app directly on its host origin.
`CSRF_FAILED`	`403 Forbidden`	The `x-copypatch-csrf` header was missing, invalid, or expired.	Log in again at `?copypatch=1` to refresh the dual-token session. If using a custom `authAdapter`, verify its `verifyMutation` implementation.
`UNAUTHORIZED`	`401 Unauthorized`	The session cookie is missing, expired, or invalid.	Authenticate via the passphrase modal or log in to your host application account.
`FORBIDDEN`	`403 Forbidden`	The authenticated user lacks the required role (`editor` for drafts, `publisher` for publishing).	Verify role assignments in your host auth system or adapter configuration.
`REVISION_CONFLICT`	`409 Conflict`	Another team member updated the active locale in the background.	Refresh the editor snapshot to view the latest copy and re-apply your changes.
`VALIDATION_FAILED`	`400 Bad Request`	Invalid content key format or payload size exceeded 64 KB limit.	Ensure content keys use alphanumeric dot-separated names (e.g. `hero.title`) and text strings are plain text.
`STORAGE_UNAVAILABLE`	`503 Service Unavailable`	Database file is locked, path is unwriteable, or PostgreSQL pool connection failed.	Run migrations (`copypatch migrate`), verify directory permissions for SQLite, or test PostgreSQL database credentials.

3. Common Symptoms & Fixes

The Editing Overlay Never Appears

Confirm the URL query parameter is exactly ?copypatch=1.
Ensure CopyPatchProvider wraps the active component tree.
Check the browser Console for JavaScript errors during lazy-loading.

Route Returns 404 Not Found

Verify that your host router mounts the handler at the exact path: /__copypatch/api/v2.
In Next.js App Router, ensure the folder name is percent-encoded: app/%5F%5Fcopypatch/api/v2/[...path]/route.ts.
In Express, ensure app.use('/__copypatch/api/v2', expressMiddleware(backend)) is declared before express.json() and SPA fallback handlers.

4. Frequently Asked Questions (FAQs)

Can I store rich-text or HTML markup in CopyPatch?

No. CopyPatch intentionally adheres to a strict plain-text invariant. Permitting HTML input creates stored XSS risks and allows non-technical editors to break CSS styling and responsive layouts.

Can I host CopyPatch on a purely static platform (e.g. GitHub Pages)?

A static export can render default fallback text, but you cannot edit or save copy on static-only hosting. An active Node.js, serverless, or container backend is required to process authenticated mutations and connect to storage.