Common issues

Quick fixes for the problems that come up most. Each entry is problem → cause → fix. For agent runs specifically, start with Why did my agent run fail?.

Actions fail with insufficient_credits

Cause. Your prepaid wallet is at (or near) zero, so credit-burning actions fail closed — agent runs, sandbox calls, connector materialise, and paid tools like web_fetch.

Fix. Top up at /a/<slug>/billing/credits; the blocked action succeeds on the next attempt. Reads and export keep working throughout. If you expected a recent top-up to be available, check for a pending purchase — a bank payment (ACH, SEPA) is not spendable until it settles. See Managing billing.

Everything blocks with spend_cap_exceeded

Cause. Month-to-date spend crossed the hard cap set at /a/<slug>/billing/caps. The cap blocks further metered calls until the next UTC month rollover.

Fix. Raise or clear the hard cap (owners/admins only), or wait for the month to roll over. See Spend controls.

A connector stopped returning data

Cause. The underlying credential is missing, expired, or the source revoked access — common with OAuth connections whose tokens lapse.

Fix. Re-check the connection and re-authorize the source, then refresh the connector. Confirm the acting principal (a teammate or agent) still has a grant on that connection — a removed grant looks like an auth failure. See Connect a source and Access model.

Model or provider errors

Cause. The pinned model isn't allowed on your account, the provider returned an error, or the platform key for that provider isn't configured (so the dispatcher can't make the call).

Fix. Pin an allowed model — see Choosing a model. If you use BYOK, confirm your own provider key is valid and has quota. If the run finished with no model call at all, it's a dispatcher short-circuit — read the run's first message for the named guard.

An agent ran but produced nothing

Cause. A run.finished with empty unit counts means no model call happened — a guard fired before the agent could think (no runtime model, missing platform key, out of credits, or a spend-cap block).

Fix. Open the run's audit trail and read the first message; it names the guard. Work through Why did my agent run fail?, which maps each guard to its fix.

An agent can't see a connection or project

Cause. Agents are default-closed — a newly installed agent sees nothing until explicitly granted access.

Fix. A human owner or admin adds a grant for the agent on that resource. See Access model.