Troubleshooting

Product-surface recipes — what you see on a page and the exact steps to clear it — live in When something shows up. This page covers wire-level and SDK symptoms instead.

Events not appearing in Investigate

  1. Check the emitter counters on the Setup page. If records shipped doesn't move, the batch never arrived.
  2. Check the SDK logs for flushAndDrain errors: a 403 means the emitter is revoked or the key doesn't match; a 409 means batch_seq went backwards (usually a second process shipping under the same emitter id).
  3. Check the spool directory. If batches are piling up there, the agent can't reach app.provantix.tech (egress blocked, DNS, TLS interception). The SDK retries with backoff; nothing is lost while spooled.
  4. Record rejected inside an accepted batch: the response counts rejections. Schema-invalid records (bad enum, missing field) are rejected individually; fix the action_type or required field and reship.

403 from /v1/batches

  • Emitter revoked? Re-register and deploy a new key.
  • Private key mangled by env passing? PEM newlines must be real newlines: PRIVATE_KEY.replace(/\\n/g, '\n').
  • Emitter id typo'd? The id in the envelope (collector_id) must be the registered one.

409 batch sequence

Sequence numbers are per emitter and strictly increasing. Common causes:

  • Two replicas share one emitter key. Register one emitter per replica (or serialize flushes).
  • The spool was wiped after batches shipped, so the SDK restarted at seq 1. Keep the spool on a persistent volume.
  • A restore from backup rewound the sequence. If this happens, contact support; we can reconcile the chain head.

Attribution shows "unknown"

The record is stored and chained, it just isn't claimed. Create (or fix) the agent record so vendor + vendor_agent_id match what the SDK emits, then check Candidates and claim the historical records. Exact matches attribute at 0.95 by explicit platform id; looser matches surface there too.

Findings marked "stale"

A finding goes stale when a scheduled reconciliation run didn't reproduce it, usually because a source was silent (connector down, import paused). Stale is not "fixed": it means the evidence stopped, and exports say so. Check connector health on the Connectors page, then let the next run re-evaluate.

A metric shows low coverage (or a missing denominator)

The coverage caption ("latency known for X% of N calls") measures your telemetry, not your agent. Low coverage means the emitter doesn't report that field — see Data expectations for which fields are optional and how to close the gap (upgrade the emitter; records are sealed and never backfilled). If coverage is high but a chart looks wrong, check the metric definitions for what the number includes and excludes.

A successful run still failed the customer

success on a record means only that the call completed without raising an error. An agent can return cleanly after doing the wrong thing — refunding the wrong account, approving the wrong invoice — and every record still reads success. This is by design: task correctness is a judgment Provantix does not make (see what Provantix does not tell you). Investigate the run's targets, arguments summaries and approvals; judge the task from those, not from the outcome badge.

Session expired loop

Session tokens live in memory; a hard browser restart signs you out by design. If the app loops you through sign-in immediately after signing in, clear site data for app.provantix.tech (a corrupted in-memory state is rare but possible) and sign in again.

Still stuck?

Email [email protected] with your organization name, the emitter id (not the private key), and the failing request id or timestamp. Never send a private key, ours or yours.