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
- Check the emitter counters on the Setup page. If
records shippeddoesn't move, the batch never arrived. - Check the SDK logs for
flushAndDrainerrors: a 403 means the emitter is revoked or the key doesn't match; a 409 meansbatch_seqwent backwards (usually a second process shipping under the same emitter id). - 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. - Record rejected inside an accepted batch: the response counts rejections. Schema-invalid records (bad enum, missing field) are rejected individually; fix the
action_typeor 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.