Troubleshooting

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:

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.

Guardrail flags look weak, or the reward verdict stays at abstain

Most weak guardrail flags and stuck abstain verdicts come from incomplete setup:

• No graph means guardrail flags cannot attach to the route model, and experiments cannot be scoped.
• No deploys means guardrail flags cannot attach to release windows, and no experiment can be registered.
• No value routes means guardrail prioritization is generic and verdicts cannot price value_at_risk.
• Too little traffic means the baseline is not ready — the mSPRT reports abstain with abstain_reason: "power" until enough sessions accumulate. This is expected, not an error; see Reward API + MCP.

Check the guardrail 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, guardrail flags, or reward verdicts are missing.
• The route, experiment id or guardrail flag id, or commit SHA involved.
• The environment: production, staging, or local.
• Whether value routes are configured for the project.