Troubleshooting & FAQs

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

1. Quick Diagnostic with CLI

The fastest way to inspect the generated configuration and required CopyPatch environment variables 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
`VALIDATION_ERROR`	`400`	A request body, locale, content key, or text value failed validation.	Correct the request shape and respect the configured text limit.
`UNAUTHENTICATED`	`401 / 403`	Authentication is missing or the principal lacks the required role.	Authenticate again and verify the adapter’s `editor` or `publisher` role mapping.
`CSRF_FAILED`	`403`	The CSRF token or host mutation verification failed.	Refresh the session; custom adapters must return `true` explicitly from `verifyMutation`.
`ORIGIN_REJECTED`	`403`	The request `Origin` does not exactly match its URL origin.	Use the same-origin API route and review the host’s trusted-proxy policy.
`RATE_LIMITED`	`429`	The unsafe-request limit for the client key was exceeded.	Wait for the retry window and verify that clients receive distinct trusted addresses.
`CLIENT_ADDRESS_UNAVAILABLE`	`503`	A Next.js unsafe request has no trusted client address.	Resolve one from the deployment platform or explicitly opt in to the shared bucket.
`REVISION_CONFLICT`	`409`	Another editor changed the published or draft revision.	Reload the editor snapshot and re-apply the change.
`UNSUPPORTED_OPERATION`	`405`	The endpoint does not support the HTTP method.	Use the method documented for that endpoint.
`INTERNAL_ERROR`	`500`	The backend could not complete the request.	Inspect server logs and storage health without exposing internal details to clients.
`NOT_FOUND`	`404`	The requested CopyPatch endpoint does not exist.	Verify the canonical `/__copypatch/api/v2` mount and route suffix.

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.