Troubleshooting

This page is organized by symptom: what you observe, what is usually causing it, and how to resolve it, with the relevant error codes linked into the error reference. A useful prior for all of it: Fibric fails closed and receipts everything, so most "failures" are the platform refusing to do something unsafe, and the receipt or error body tells you which rule refused it.

#First moves for any incident

# who am I acting as, and is the key valid?
fibric auth whoami

# are the connectors healthy? probes catch credential problems first
fibric connectors list

# what actually happened? the receipt ledger is the ground truth
fibric receipts tail

Every API error body carries a stable error.code and a request id; include the request id when contacting support. Retryability by status code is tabulated in Errors.

#Connector auth expired or rejected

Symptom: a connector's status shows error in fibric connectors list or the console; tool calls against it fail; receipts show actions failing with upstream authentication errors; a connector test returns auth_failed.

Error codes: auth_failed on install or test; connector_upstream_error when the source rejects calls mid-operation. Note the distinction from key_invalid/key_revoked, which are about your API key, not the connector's credential; see Errors.

#Events stalled

Symptom: operators stop proposing, dashboards flatline, or a stream goes silent while everything reports healthy.

Work from the source inward; the failure is almost always at the first hop that has no new data.

Error codes: rate_limited, invalid_cursor, connector_upstream_error.

#Action vetoed or blocked

Symptom: an operator proposed something and it did not happen. The receipt shows a disposition of BLOCK, or a plan sat in approval and a human vetoed it.

First, read the receipt: it records which policy refused the action, or who vetoed and why. Then distinguish the three cases, because their remedies differ:

An API request whose actions were all refused fails with policy_blocked, and the body carries the per-action verdicts. If the operator's capability is not fulfilled by any installed connector at all, you get capability_unbound instead: install and bind a connector for that capability (Capabilities).

#Duplicate suppressed

Symptom: a receipt shows DEDUP, or an API write returns 409 idempotency_conflict, or "the same" event you sent twice appears once.

Key-design guidance is in Single-flight & idempotency and Reliability.

#Requests failing with entity_locked

Symptom: writes intermittently return 409 entity_locked with a Retry-After header, usually under bursts touching the same order, conversation, or asset.

Cause: the single-flight lock for an entity_key your request needs is held by other in-flight work. This is transient by design: the lock releases when that work disposes.

Resolution: wait for Retry-After, then retry the same request unchanged, same idempotency key, so the retry is dedup-safe. If one entity is persistently locked, something is holding it with slow work: check fibric receipts tail for a long-running action on that entity, and check whether your entity keys are broader than the real entity (for example, keying a whole store rather than one order serializes everything behind one lock). See Errors and Single-flight & idempotency.

#Quota or rate limit exhausted

Symptom: requests return 429. Two different codes, two different problems:

#Other frequent symptoms

If a symptom here does not match yours, the error reference covers every code the API returns, with retryability guidance, and Reliability and delivery semantics defines what the platform guarantees under failure. For anything that looks like a security issue, go straight to responsible disclosure.