TrueClaradocs
GitHub
Help/Troubleshooting

Troubleshooting

Diagnose missing graphs, missing runtime events, missing deploys, weak observations, and incorrect value-route priority.

Start with the project setup screen. It shows parser, runtime, deploy, repository, and test-event health in one place.

Map is empty

Upload the static graph:

Terminal
npx @trueclara/parser . --pretty -o trueclara-graph.json
curl -X POST https://api.trueclara.com/v1/static-graphs \
  -H "Content-Type: application/json" \
  -H "X-Trueclara-Project-Key: $TRUECLARA_PROJECT_KEY" \
  --data-binary @trueclara-graph.json

If upload fails, check the write key and parser output. The graph must include a schema version and a routes array.

No events are arriving

Check these in order:

  1. The app uses the public key for the project you are viewing.
  2. TrueClaraProvider wraps the Next.js app shell.
  3. Your consent bridge is not holding the SDK at none.
  4. The browser can reach the SDK event endpoint.
  5. The project setup test event succeeds.

If the test event works but browser events do not, inspect provider placement and consent state first.

No deploys are arriving

Check that CI uses TRUECLARA_PROJECT_KEY, not NEXT_PUBLIC_TRUECLARA_KEY.

Then confirm the deploy payload includes:

  • commit_sha.
  • environment.
  • static_graph.
  • The graph generated from the exact app version being deployed.

Use GET /v1/deploys/last?environment=production with the same write key to verify the API can see prior deploys for that project.

Observations look weak

Observation Detail (THEME (light))
Observation detail is where route, deploy, and evidence context come together.

Most weak observations come from incomplete setup:

  • No graph means observations cannot attach to the route model.
  • No deploys means observations cannot attach to release windows.
  • No value routes means prioritization is generic.
  • Too little traffic means the baseline is not ready.

Check the observation evidence panel before changing detector thresholds.

Value-route priority looks wrong

Confirm the configured route pattern exists in Map or the Routes table. Use route patterns such as /projects/[id], not raw paths such as /projects/123.

If the route represents an entry point rather than completion, remove it from value routes and mark the actual success or activation route instead.

What to include when asking for help

  • Workspace and project slug.
  • Whether Map, runtime events, deploy upload, or observations are missing.
  • The route, observation id, or commit SHA involved.
  • The environment: production, staging, or local.
  • Whether value routes are configured for the project.