Troubleshooting

​

SDK requests fail with 401 or 403

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key"
  }
}

​

Parameters resolve to their defaults

1. The bundle was never fetched. If the config request fails, SDKs fall back to code defaults silently. Check the network tab (or server logs) for GET /v1/config/:projectId. A 404 with Bundle not found for <projectId>/<env> means the project ID or environment name is wrong — the env defaults to production, so a typo’d or unpublished environment 404s.
2. Wrong environment. Bundles are per project and environment. If you configured overrides in one environment but the SDK fetches another, you’ll see that other environment’s defaults.
3. The served bundle is a stale copy. A 200 response carrying the X-Traffical-Bundle-Stale: true header means the config store was briefly unavailable and Traffical served the last known bundle — a change you just published may not be in it. This resolves itself within moments; the stale response carries a shorter cache TTL so clients revalidate aggressively.
4. The policy isn’t running. Only policies in the running state — and inside their start/end schedule window, if one is set — are included in the bundle. Draft, paused, and completed policies resolve to defaults. Check the policy’s state badge on its detail page.
5. The unit key is missing from the context. If the evaluation context doesn’t include the project’s unit key field (for example userId), the layer is skipped entirely: no bucket, no policy match, defaults for every parameter in it — and no exposure is recorded. In multi-entity projects, a layer randomizing on a different entity needs that entity’s key in the context.
6. Targeting conditions don’t match. A policy whose conditions don’t match the context is passed over. Test with a context you know should qualify.

​

Events aren’t showing up

1. The key can’t write. Sending events needs sdk:write; without it the whole batch is refused with 403 and SDK write scope required.
2. Schema enforcement rejected them. If the event’s definition has schemaEnforcement: reject, an event violating the property schema is dropped and reported in the response’s validationErrors array with Schema validation failed: .... In warn mode the event is stored and the violations appear in schemaWarnings instead — so “warn shows data, reject shows nothing” is the tell. See property schemas.
3. The event name doesn’t match its definition. Metrics aggregate a specific event definition by exact name. A typo’d name (purchase_completed vs purchase) doesn’t error — it accumulates as a separate auto-discovered event while the metric it was meant to feed stays flat.
4. The event is structurally invalid. Events missing type or unitKey are skipped individually and reported in validationErrors; the rest of the batch is still accepted.

​

A policy shows no results

1. No goal metric attached. Results are computed per attached metric; a policy with none has nothing to analyze. For adaptive policies this also stalls optimization — the health view reports Optimizer has no reward source: no primary metric attached. On the policy’s detail page, open the metrics panel and click Attach Metrics (how).
2. Not enough sample yet. Guardrail evaluation reports insufficient_data for any treatment allocation with fewer than 30 users, and early confidence intervals — especially sequential ones — are wide by design. This is the system refusing to call it early, not a malfunction. Measurement progress shows how far along the experiment is and a runtime estimate.
3. You’re ahead of the analysis schedule. Health and SRM checks refresh on a fast lane (every 5–15 minutes), but metric results — significance, lifts — are recomputed on the full analysis run, typically every two hours. An event sent seconds ago won’t move a result yet, and flat results half an hour after launch are normal. Check freshness and recent runs on the Pipeline page.

​

A sample-ratio mismatch (SRM) warning

• Targeting or allocation edits mid-flight. Changing weights or conditions on a running policy shifts who lands where from that moment on, while the window still contains the old regime. (Adaptive policies are handled for you: the check re-baselines at each optimizer rebalance, so a legitimate rebalance won’t trip it.)
• Caching. Clients holding an old config bundle keep serving the old split. Long-lived server processes that never refresh, or an aggressive CDN in front of your own config fan-out, are the usual suspects.
• Differential exposure loss. One variant loses its exposure events more than the other — a redirect variant dropping users before the SDK flushes, a variant that crashes a webview, ad-blockers firing on one page layout but not the other.

​

A guardrail is breaching

• warning flags the change for human review. Nothing is stopped automatically.
• blocking is enforced: when a blocking guardrail turns failing on a running phase, the monitor applies the phase’s armed breach action — pausing the policy by default; reverting or merely recording only when configured — and writes a decision record citing the evidence. If a change paused itself, this is why; the decision record names the guardrail.

​

Warehouse connection failures

​

A change can’t start traffic

1. No certified protocol covers the change. The start is blocked with: “No certified measurement protocol matches this change — a human must approve a measurement plan before exposing traffic.”
2. Certified coverage, but not auto-approvable. Auto-approval requires all of: low risk class, a plan resolved entirely from certified protocols, and zero unresolved risks. Any medium, high, or critical change — and any plan carrying a coverage gap — waits for a human. High- and critical-risk changes never start without a person signing off; see risk classes.
3. The plan is structurally invalid. Multiple primary metrics with no designated objective is a hard block even for a human approver — the plan must be disambiguated first.

​

MCP client can’t connect

1. Wrong key type. SDK keys (sdk:read/sdk:write) — including the key the CLI provisions into .traffical/.env — cannot access the MCP server and get a 403 FORBIDDEN naming the missing management scope. Use a management key with mgmt:read (read-only) or a write scope, or the OAuth flow.
2. OAuth token minted for the wrong resource. Tokens are audience-bound: a token minted for anything other than the MCP resource gets a 401 whose WWW-Authenticate header points at the OAuth discovery document. Clients that follow standard discovery recover automatically; re-run your client’s auth flow (/mcp in Claude Code).
3. Write tools missing from tools/list. The tool list is scope-filtered — a token without changes:propose / changes:operate / defaults:promote simply never sees the write tools. This is a token-scope issue, not a server outage.
4. Transitions rejected outright. MCP write mode is off (the default) or set to advisory. In off, create_change still authors drafts but its start leg is refused; in advisory, every transition is capped at a proposal for human review. That’s governance working as designed, not a failure.

​

Still stuck?