Troubleshooting
| Symptom | Check |
|---|---|
| Connection refused on localhost | Listener enabled, correct port, desktop background service running; container localhost is not the host. |
| 401 | Correct destination token, Bearer header, expiry and revocation. |
| 403 | Scopes, resource grant, workspace membership, active API/logging entitlement. |
| 404 | Base URL, route, workspace/resource UUIDs, and destination resource existence. |
| 400 or 422 | JSON syntax, endpoint-specific fields, timestamp timezone, supported severity, and schema constraints. |
| 409 | Read the returned error: revision/idempotency conflicts and admission conflicts require different recovery. |
| 413 | Reduce batch size; compressed and decompressed limits both apply. |
| 429 | Respect Retry-After and inspect quota/usage; use bounded backoff. |
| 5xx or timeout | Retry with backoff; a timed-out write may already have succeeded. |
| Accepted logs are absent | Correct destination/resource, separate read permission, filters, retention, and forwarding status. |
| Desktop forwarding paused | Correct cloud URL/key, then use Retry. Full queues can skip additional cloud copies. |
Collect useful diagnostics
Record HTTP status, response error code/message, request ID when returned, timestamp with timezone, route, and destination. Redact tokens, cookies, payload secrets, and personal data before sharing diagnostics. Cloud and local error envelopes may differ; inspect the response rather than assuming one format for every endpoint.
Use the live cloud reference to check deployed behavior. Documentation's schema snapshot records the reference used for this publication.