Lazers/Documentation/Operational Troubleshooting Guide
Troubleshooting

Operational Troubleshooting Guide

Diagnostic matrix covering authentication errors, rate limiting, dropped signals, and OTLP rejections.

Use this operational reference to quickly diagnose and resolve telemetry delivery issues.

Scenario Resolution Matrix

No signals received

Symptom: Dashboard shows 'Awaiting first signal' after running test script.
Likely Cause: Telemetry was sent to wrong endpoint, environment mismatch, or process exited before flush.
Fix: Ensure client calls await client.flush() or client.close() before process exit, and verify LAZERS_ENVIRONMENT matches the environment selected in the Lazers console.

401 Unauthorized

ERR_AUTH_UNAUTHORIZED
Symptom: HTTP 401 error response on POST /signals/ingest or /v1/logs.
Likely Cause: Missing x-lazers-api-key header or invalid server API key.
Fix: Confirm you passed a server API key beginning with 'laz_live_' in the 'x-lazers-api-key' header. Do not use client DSNs on server endpoints.

403 Forbidden

ERR_AUTH_FORBIDDEN
Symptom: HTTP 403 error response during ingestion.
Likely Cause: The API key has been revoked, disabled, or belongs to a different project.
Fix: Navigate to Project Settings -> API Keys in the Lazers console, verify the key status is ACTIVE, or generate a replacement key.

Invalid API key format

ERR_INVALID_KEY_FORMAT
Symptom: Ingestion rejected with 'Invalid API key format'.
Likely Cause: Whitespace in key or placeholder value used (e.g. 'laz_live_REPLACE_ME').
Fix: Copy the full secret key once during generation. Server API keys must begin with 'laz_live_'.

Invalid client DSN

ERR_INVALID_CLIENT_DSN
Symptom: Flutter SDK throws DSN validation exception on init.
Likely Cause: DSN uses HTTP instead of HTTPS, contains query strings, or uses a server API key.
Fix: Use the write-only client DSN beginning with 'https://laz_ci_' generated under Project Settings -> Client Credentials. Never pass server keys to Flutter.

Wrong environment reporting

Symptom: Signals appear in 'production' instead of 'staging' or 'preview'.
Likely Cause: Hardcoded environment string in SDK init or missing LAZERS_ENVIRONMENT variable.
Fix: Set LAZERS_ENVIRONMENT=staging in your deployment environment variables, or pass the explicit environment slug in SDK configuration.

Network timeout

ERR_NETWORK_TIMEOUT
Symptom: SDK logs warning 'Lazers telemetry timeout' or drops signal after 5 retries.
Likely Cause: Outbound firewall or proxy blocking requests to https://api.lazers.app:443.
Fix: Whitelist outbound HTTPS traffic to api.lazers.app. In server SDKs, adjust timeoutMs (default 5000ms) or configure an HTTP proxy transport.

429 Rate limited

ERR_RATE_LIMIT_EXCEEDED
Symptom: HTTP 429 Too Many Requests response from ingestion endpoint.
Likely Cause: Client DSN rate limit exceeded (default 60/min) or server project rate cap reached during an alert storm.
Fix: Increase per-minute rate limit in Client Credential settings, or check for recursive unhandled error loops in application catch blocks.

Signal dropped silently

Symptom: Specific error was caught by app but does not appear in Lazers.
Likely Cause: Queue overflow (queue capped at default 100 items), process killed before flush, or non-retryable 4xx payload error.
Fix: Increase maxQueueSize if bursty; ensure shutdown hooks call flush(); inspect console output for validation errors.

Release version missing

Symptom: Signal shows 'No release' on incident detail surface.
Likely Cause: Release was not provided or used a rejected placeholder ('git-sha', 'unknown', 'replace-me', 'undefined').
Fix: Supply an authentic release string such as the commit git SHA (e.g. 'c80c6d2'), semantic version ('v2.4.1'), or build number ('build-142').

Actor / Customer context missing

Symptom: Affected user count remains 0 on incidents.
Likely Cause: SDK capture calls did not include an actor object with a stable ID.
Fix: Pass actor context: { type: 'user', id: user.id } on captureError or call LazersFlutter.setActor(id: user.id, type: 'user'). Do not pass email/phone.

OTLP payload rejected

ERR_OTLP_UNSUPPORTED_PAYLOAD
Symptom: OpenTelemetry collector logs export error from otlphttp/lazers.
Likely Cause: Collector attempting to send metrics, protobuf format, or missing 'x-lazers-api-key' header.
Fix: Lazers OTLP v0.1 accepts JSON logs (/v1/logs) and traces (/v1/traces) over HTTP. Ensure the collector pipeline only points logs and traces exporters to Lazers with header 'x-lazers-api-key: laz_live_...'.

Ready to test with your service?

Create a project, generate an API key or Client DSN, and send a signal in 2 minutes.