Troubleshooting
Use a repeatable method to diagnose setup, runtime, storage, and analytics problems.
Troubleshooting is faster when you follow the data path instead of changing several resources at once.
1. Confirm context
Check the signed-in workspace, selected project, environment, and public origin. Many apparent missing-resource problems come from viewing staging while sending to production or vice versa.
2. Confirm the contract
Open the data model or generated OpenAPI document. Compare the exact model key, required fields, types, and allowed filter operators with the request.
3. Confirm identity and scope
Verify the client/key is enabled and belongs to the intended project. Check allowed models or Analytics APIs, CIDRs, JWT/mTLS configuration, and identity-binding values.
4. Locate the failed stage
| Signal | Stage reached |
|---|---|
| Connection fails | DNS, network, TLS, or listener |
401 | Runtime reached; authentication failed |
403 | Authentication succeeded; policy failed |
400 before ingest ID | Request/model validation failed |
202 with ingest ID | Accepted into delivery path |
| Live activity but no warehouse row | Inspect destination/dispatch |
| Warehouse row but empty analytics | Inspect definition, filters, time range, and cache |
5. Change one thing
Use a minimal test record or query. Avoid rotating credentials, editing the model, changing CIDRs, and replacing destinations simultaneously; that removes evidence.
6. Account for freshness
New runtime resources can require a short configuration refresh. Query results can use a configured TTL. Retry within a bounded window and identify which freshness mechanism applies.
7. Collect safe evidence
Keep timestamps, status codes, resource IDs, ingest IDs, selected model/analytics keys, source IP, and redacted request shape. Never include secrets or private keys.