Troubleshoot Claron setup, capture, and access
Start with the symptom you see. Check the project and deployment first, then follow the relevant setup guide. A new configuration cannot recover evidence that was never captured.
Before you start
The affected project, report or build, and the error message.
What you get
Find the next useful check without repeating the entire setup.
The preview build failed
Read the build log
Find the first actionable error. Missing dependencies, incorrect paths, and missing variables have different fixes.
Check the application configuration
Confirm the repository branch, monorepo root, install/build commands, output, and required variables. A static build and an SSR server need different output settings.
Retry after correcting the cause
Open Builds & Previews for the failure checklist. Use Environment Variables for missing configuration.
An element has no source context
Check the actual deployed build
Confirm the report belongs to the intended project and commit. Adding the SDK locally does not change an existing deployment.
Check the matching frontend integration
Use the frontend SDK for JSX/TSX or the dedicated hosted template integration. Next.js needs the webpack path; the generic Vite plugin does not instrument Vue, Svelte, Astro, or Angular templates.
Make a new element report
Verify that the supported element has data-claron-src, then submit a new Element annotation. Runtime-created or third-party elements may have no direct token. Source-map upload is separate from compiler tagging.
Backend evidence is missing or locked
| Symptom | Next check |
|---|---|
| Locked on this device | Use the correct diagnostic recovery file and original password on an authorized device. See unlocking evidence. |
| No captured server request | Confirm the selected environment, registered backend origin, running application, and collector. Run backend doctor, then capture a new review request. |
| Setup rejects the framework | Check framework compatibility. Some SDK adapters are implemented before their automatic CLI installers become available. |
| Evidence is incomplete | Read its completeness state. An interrupted request, timeout, or unsupported operation can leave partial context. Do not assume that nothing ran. |
A reviewer cannot join or report
Check the invitation and account
Use the intended Claron account and a valid invitation for that project. Read Review Sessions or Review Rounds for the appropriate invite type.
Check permissions
Project access, review access, and diagnostic access are separate. Match the task to the user's effective role; an invite does not grant every developer action.
Check the website session
Sign in to the website normally. For a protected hosted preview, follow Authenticated Previews. The production extension cannot bypass website authentication.
A screenshot or replay is missing
Check capture permissions and state
Confirm the requested browser permissions and whether the screenshot is queued, successful, failed, or expired. A missing image is not the same as a successful empty screenshot.
Reproduce in a new active review
Capture must be enabled before the action. Old reports cannot gain uncaptured history. Check the extension setup or replay guidance.
Use the supported verification path
Production extension reports use human verification; automated after screenshots and pixel comparisons are not available in that workflow.
CLI setup or dashboard handoff fails
Check the installed command
Run claron --version and the relevant command's --help. Backend setup should describe environment names and automatic local collector provisioning. Update a distribution that still requires the old manual flow.
Check account and repository
Confirm the intended account, project link, and repository root. For fix workflows, check the checkout against the report's deployed commit. See CLI authentication.
Use the terminal if the browser handoff fails
Run claron ui --view with the real issue UUID, or claron apply with that UUID, from the linked repository. Review the workflow before confirming a patch.
An integration or MCP connection fails
| Connection | Next check |
|---|---|
| Issue tracker or chat provider | Check provider authorization and the saved destination. Test checks the connection; then push a sample report or trigger a relevant notification. See provider setup. |
| Webhook | Check its destination, subscribed event, delivery outcome, and signature handling. See Webhooks. |
| MCP | Check the endpoint, credential with mcp:read, and eligible project role. The connection reads existing evidence; it does not create reports or decrypt backend evidence. See MCP setup. |