Events not appearing in the dashboard

Events pass through four checkpoints before they appear in the dashboard: the agent must be sending, the core URL and key must be correct, the buffer must flush, and the encryption keys must match. Work through the tree below in order. Each section tells you how to confirm the symptom and what to fix.

Start here

Answer each question in sequence. Stop at the first match.

1. Is the agent even sending? - Check whether enable_agent=True and the process restarted after the config change. If not, go to Is the agent even sending?

2. Is agent_endpoint correct and is the key valid? - The agent logs 401 on a bad key and silently misdirects on a wrong URL. Go to Wrong core URL or key.

3. Did you just deploy or restart? - The buffer flushes on a time or size trigger, not per request. If events should be there but are just delayed, go to Buffer hasn't flushed yet.

4. Did you rotate the project encryption key recently? - Agents hold the key in memory. A rotation without a restart leaves the agent sealed with the old key. Go to Encryption mismatch.

5. Is the agent returning 429s? - The agent self-throttles on 429 rather than retrying immediately. Go to Rate limited by core (429).

6. None of the above apply - Go to Still stuck.

Is the agent even sending?

Symptom: no events in the dashboard, no errors in logs, clean startup.

How to confirm: check SecurityConfig for enable_agent=True. If it is False or absent, the agent is constructed but never starts the flush loop. Nothing is sent.

SecurityConfig(
    enable_agent=True,
    agent_api_key=API_KEY,
    agent_project_id=PROJECT_ID,
    agent_endpoint="https://api.guard-core.com",
)

Only two fields are required to start delivery: enable_agent must be True and agent_api_key must be set and non-empty. If either is missing, to_agent_config() returns None and the agent never starts. All delivery is silenced. agent_endpoint has a default (https://api.guard-core.com), and agent_project_id is optional: when it is absent, events still deliver under the "default" project bucket, and only dynamic-rules polling (which needs the X-Project-ID header) is disabled.

Fix: set enable_agent=True and agent_api_key, then restart the process. Trigger a request and wait one agent_flush_interval. Events should appear.

See the credentials table in API keys & encryption setup.

Wrong core URL or key

Symptom: agent started, but still no events. Logs may show repeated 401 responses.

How to confirm: a 401 means the key was presented but rejected, either it is wrong, it was revoked, or it belongs to a different project. A common agent_endpoint mistake is appending /api/v1 yourself, but the agent guards against it: on startup the config validator detects a trailing /api/v1, strips it, and logs a warning before any flush, so the bare host is what actually gets used. Grep your startup logs for that strip warning (ends with '/api/v1'), if you see it, your config still carries the suffix even though delivery is unaffected. The 401 case is separate: look for repeated 401 responses, which mean the key itself was rejected.

The agent presents the key as X-API-Key on every flush. The core stores only the SHA-256 hash. The 401 response is identical for a wrong key and a missing key, so the log line alone does not distinguish between the two.

Fix:

• Confirm agent_api_key matches what the dashboard shows under Settings → API Keys for the project.
• Confirm agent_project_id and the key belong to the same project.
• Confirm agent_endpoint is the bare host https://api.guard-core.com (or your self-hosted equivalent) with no /api/v1 suffix. The agent appends /api/v1/events itself. If you do add the suffix, the config validator strips it on startup and logs a warning, so delivery still works; clean up the config to clear the warning.
• If in doubt, revoke and create a new key from the dashboard, then update agent_api_key and restart.

Buffer hasn't flushed yet

Symptom: events are expected but do not show up immediately after deploy or a low-traffic period.

How to confirm: the agent does not send one HTTP request per event. It queues events in an in-memory buffer and flushes on a size or time trigger. If the buffer has not hit 80% capacity and the agent_flush_interval has not elapsed, events are still queued. This is normal, not a bug.

The flush fires when either condition is true: the buffer is at or above 80% capacity, or agent_flush_interval seconds have elapsed since the last flush. At low traffic, the time trigger dominates; the default interval controls how stale buffered events can get.

Fix: wait one agent_flush_interval after triggering a request. If events still do not appear after that window, the issue is elsewhere in this tree.

For sizing and overflow behavior, see Agent buffering & backpressure.

Encryption mismatch

Symptom: events were flowing, then stopped immediately after a key rotation. No 401s in logs. The agent appears to be flushing (no errors), but the dashboard shows nothing new.

How to confirm: the agent holds agent_project_encryption_key in process memory, loaded at startup. After a rotation, the project key is overwritten immediately. There is no overlap window and no historic fallback. Events the agent emits using the old key in memory cannot be decrypted by the core and are rejected.

The telemetry payload is sealed with the single current project key as plain nonce + ciphertext. There is no version marker and the core keeps no ring of old project keys. It decrypts every batch with the one active project key, so a batch sealed with the old key fails AES-GCM authentication and the core responds HTTP 400 Failed to decrypt payload. (The version-marker key ring elsewhere in the system protects only the stored project key under the master KEK, not the telemetry payload.)

Fix: update the GUARD_PROJECT_ENCRYPTION_KEY environment variable (or however you inject the secret) to the new plaintext returned by the rotation response, then restart every agent instance. Once the new key is loaded at startup, fresh events seal with the correct key and appear in the dashboard.

If you have multiple replicas, events from un-rotated instances will continue to fail until each restarts. The mismatch window lasts until all replicas have restarted.

See the full rotation procedure in Encryption key rotation.

Rate limited by core (429)

Symptom: events visible for a while, then gaps or delays. Logs show 429 responses from the core.

How to confirm: the agent does not retry immediately on 429. It hands control to its internal rate limiter, which paces subsequent flushes until the core stops returning 429. This is intentional. Retrying immediately on 429 would amplify the load that triggered it.

During self-throttling, events continue to queue in the buffer. If the throttle period outlasts the buffer's capacity, overflow eviction begins silently.

Fix: check your plan tier and event quota in the dashboard. Persistent 429s during normal traffic indicate you are near or over the plan quota. Options: reduce event volume at the source (filter low-signal events, disable metrics if not needed), upgrade the plan, or raise agent_buffer_size to absorb the throttle window without overflow.

See Agent buffering & backpressure for how the agent handles 429 and self-throttling behavior.

Still stuck

If none of the sections above matches, contact support from the dashboard. Include the agent version, your SecurityConfig fields (with credentials redacted), and the relevant log lines.