Events not showing up
The single most-common Beacon support question is “I sent events from my application but they’re not appearing in the dashboard.” This page walks through the diagnostic order — from fastest to slowest signal — so you can pinpoint where in the pipeline things went wrong.
Step 1 — Decide which surface you’re checking
Beacon’s pages have three different freshness profiles, and confusing them is the easiest way to chase a non-existent bug.
- Live (within seconds of SDK flush): Invalid Events, Actor Identities, Funnels, Property Explorer (key list).
- Aggregated every 15 minutes: Dashboard, Event Explorer, Sessions, Usage Insights, and the per-key Property Explorer breakdown views.
- Recomputed once per day (overnight UTC): Retention cohorts, Anomalies.
If you’re checking the Dashboard or Event Explorer right after firing a test event, the absence of your event is expected — wait up to 15 minutes, or use a live page. Retention cohorts and Anomalies for today won’t appear until the next overnight pass.
Step 2 — Check Invalid Events
In the sidebar, expand Data and click Invalid Events. This page shows events the API received but rejected. Updates within seconds of ingestion.
If your event is on this page, the SDK reached the API but the payload was rejected. Common error codes:
| Error code | What it means | Fix |
|---|---|---|
UNRECOGNIZED_PRODUCT | The event’s source_app doesn’t match any product in your organization | Re-check that the slug matches exactly (case-sensitive) — "InventoryManager" vs the actual slug "inventory-manager" is a frequent foot-gun. Slug lives at Settings → Products. |
UNREGISTERED_VERSION | Strict version mode is enabled for the product and the event’s source_version is not pre-registered (or is archived) | Register the version on the product’s Versions page, or turn off strict mode. See Strict version mode. Rejected events are NOT auto-retried by the SDK — they are permanently lost. |
ALLOWLIST_REJECTED | An active allowlist exists for this (source_app, source_version) and your event’s (category, name) isn’t on it | Either add the missing entry to a new staged allowlist and activate it, or revisit whether the event is one you want to track. See Create your first allowlist. |
PAYLOAD_TOO_LARGE | Individual event > 4 KB serialized JSON | Trim the data — usually a stack trace or large free-form property |
PROPERTIES_TOO_MANY_KEYS | Event has more than 20 properties | Reduce to 20 or fewer |
PROPERTIES_KEY_TOO_LONG | A property key exceeds 64 characters | Shorten the key |
PROPERTIES_VALUE_TOO_LONG | A property value exceeds 256 characters | Shorten or hash the value |
INVALID_UUID | A field that strictly requires a UUID (e.g., event_id) got a non-UUID value | Verify your SDK is generating valid UUIDs. UUID v7 is recommended. |
INVALID_FIELD_FORMAT | An optional field with a format constraint (e.g., session_id if provided) got an invalid value | Check the malformed field; the validation error includes the field name |
REQUIRED_FIELD_MISSING | A required payload field is missing (event_id, category, name, timestamp, actor_id, source_app, source_version) | The error includes the field name. Confirm your SDK is constructing the event payload correctly |
Step 3 — Check live cross-references
If the event is not in Invalid Events, the SDK may have reached the API and been accepted (good) — or never reached the API (bad). To distinguish:
- If you called
Identifywith a fake actor ID: open Actor Identities (under Explore). Your test actor should appear within seconds. If it does, ingestion is confirmed; just wait for the aggregator to roll up your test event. - Otherwise: check the SDK’s last-flush diagnostic. All three SDKs expose this:
- .NET:
tracker.LastFlushStatus(returns aFlushStatuswith success/error/timestamp) - C++:
tracker->last_flush_status() - JS: enable
debug: truein the config; flush results log to console
- .NET:
If the last flush errored: 401 = wrong API key; 402 = ingestion blocked (see Cap exceeded behavior); 429 = rate limited (SDK retries automatically).
Step 4 — Check your network
The SDK sends to https://api.beacon.softagility.com over outbound TLS. If your app runs behind a corporate proxy or firewall, that hostname needs to be on the outbound-allowed list. Test from a terminal on the same machine: curl -I https://api.beacon.softagility.com/health — a 200 OK confirms reachability.
Step 5 — Verify SDK configuration
If the network is fine and the SDK still isn’t reporting, it might never have initialized. Common configuration mistakes:
- API key copied with whitespace. A leading or trailing space invalidates the key. Re-copy from Settings → API Keys.
- Wrong API base URL. Should be
https://api.beacon.softagility.comexactly — not the dashboard URL. AppNamedoesn’t match a registered product slug. SeeUNRECOGNIZED_PRODUCTabove.
Enable the SDK’s logger / debug mode. The .NET and C++ SDKs log a “disabled — required options missing” warning if ApiKey / AppName / AppVersion is missing (the tracker no-ops rather than throwing). The JS SDK throws during initialization in the same case, surfacing the failure immediately.