Troubleshooting

Organized by where you are, not by error code. Find your situation below, read what's actually happening, then what to do about it.

Publishing and builds

A draft won't publish. The agent editor's Publish button stays unavailable until every blocking issue is resolved, and diagnostics point at exactly which section is at fault. For an Agent, the confirmed blocking cases are an empty persona (required to publish — the editor flags it as a warning while you're still typing, but Publish stays disabled until you write one) and a model override that isn't on the workspace allowlist. For a Workflow, publish is blocked while the pipeline isn't runnable: no steps at all, an agent step with no Agent chosen or one that has no published version, a tool step on a connection that's missing, disabled, or personal rather than workspace-scoped, an empty prompt, an @ reference that's illegal for its position, or an invalid cron expression. Every finding is attached to the step or trigger it concerns — resolve the flagged card.

A connection referenced by an Agent's context was deleted or disabled. The Agent won't compile until you re-equip a replacement connection or remove the reference from its Context section.

Publish fails after a build error. The build itself failed compiling — check the error text shown in the red-bordered box on the agent editor's rail. If the message doesn't point at anything you can fix by editing the persona, model, or context, that's a genuine platform-side issue, not something you can self-correct by re-editing prose.

Chat and runs

A message is rejected because the session is busy (session_busy). A run is already active on that session, or one is parked waiting on you — either way, this is transient. In Chat's own UI this is handled automatically: your message queues instead of failing, and sends the moment the session frees.

A thread stops accepting any new message, permanently (session_not_active). The underlying session itself is gone — unknown to eve, already finished, reset, or timed out after a long period of inactivity. This is permanent for that session: never retry it. Start a new chat instead.

These two are easy to conflate but are never the same fix: session_busy means wait and retry: the session is still alive, just occupied. session_not_active means start over: the session itself no longer exists.

Cancelling a run doesn't stop an in-flight tool call immediately. Cancellation is cooperative — it takes effect at the next durable step boundary, so a tool call already running finishes rather than being torn in half. This is intentional, not a bug: it avoids leaving a half-finished side effect (like a partially sent message) in an undefined state. The run still lands canceled, never failed.

A session-limit prompt interrupts a long conversation. This is eve's own input-token budget guardrail, not something invisible-string imposes — approve to continue with a fresh budget, or stop. See Limits and defaults for the exact threshold.

Connections and OAuth

A connection shows Unreachable. The server itself couldn't be reached — check its URL and that it's actually running.

A connection shows Auth required. No credentials are configured yet — add them, or complete OAuth consent.

A connection shows Auth error. Credentials are configured, but they were rejected — they're wrong, expired, or revoked. Rotate them or reconnect.

A tool call fails mid-run asking you to reconnect a connection. The stored OAuth grant is dead — an expired refresh token, a revoked grant, or a connection that never fully completed consent. Re-run the OAuth consent flow on the connection; there's no automatic recovery from a dead grant.

A connection won't delete. Something still references it — typically an Agent's context, in its draft or a published version. Remove the reference first, then delete the connection.

Community search stops returning results, but the catalog still installs fine. The search index (Meilisearch) is down or unconfigured. This degrades only community search — the catalog and custom-URL lanes keep working — and it self-heals with a full resync once the index is back.

Triggers and delivery

A webhook returns 401. The ingress token is wrong or was rotated — mint a fresh trigger token and update whatever calls it.

A webhook returns 413. The request body exceeds the size cap — see Limits and defaults.

A webhook returns 429. You're over the rate limit — back off per the Retry-After header the response carries.

A trigger fired but no run started. Check the Runs tab first: by default a Workflow runs one pipeline at a time, and a trigger firing while the previous run is still live is skipped, not queued — a webhook or form dispatch still answers 2xx, with a body saying "reason": "overlap_skipped". If nothing was running, confirm the Workflow is actually published: drafts never dispatch.

A scheduled Workflow fired once instead of catching up on several missed windows after downtime. This is the intended no-backfill design, not a bug: the schedule ticker always advances the next fire time from now, so a control plane that was down across several windows fires once on recovery and resumes its normal cadence.

A step failed with a tool or argument error and never retried. By design: only transient failures — the server unreachable, a timeout, a 429, a 5xx — are retried. A tool error or invalid-arguments answer means the server is up and said no; retrying the same call would just fail the same way. Re-check the tool name and argument shapes against the connection's tool picker, and use Test step to see the real response.

A run failed fan_out_exceeded or output_too_large. The pipeline hit a hard cap: a For each was handed more items than its limit allows, or a step produced more output than the per-step cap. Both fail loudly instead of silently truncating — truncation would corrupt whatever depends on the data. Narrow the search a tool step runs, or lower how much a step returns; the caps themselves are listed in Limits and defaults.

A published Workflow shows a staleness warning. Its published snapshot references something the workspace no longer has in dispatchable shape — an Agent that was unpublished or deleted, a connection that was removed or disabled. The Workflow still fires, but the affected step fails at run time. Fix the resource (or the step) and republish.

A Slack-triggered run succeeded but nothing was posted to Slack. A reply posts only when the Workflow's configuration declares one (onComplete.slackReply) — no declared reply, no post, by design. The run's record is its step timeline in the Runs tab.

A Slack reply — or a tool step's side effect — landed twice after a crash or restart. Expected: reply delivery and default tool steps are both at-least-once, not exactly-once. A crash inside the narrow window between doing the thing and recording that it was done repeats it on recovery. A tool step whose side effect must not repeat can opt into at-most-once, which fails as interrupted instead of re-firing.

Self-hosting

Full detail lives in Deploy your own; the short version of the three most common issues:

• Every chat send fails instantly with a 502, even though health checks look fine — check for an uppercase WORKER_ID. It must be lowercase.
• Instant 502s on chat sends or run streams through the edge proxy on an older image — a disabled idle timeout cutting quiet connections. Upgrade the image, or set SSE_HEARTBEAT_MS lower as a stopgap.
• Builds reference artifacts that are missing after a partial restore — clear the stale builds rows so they re-run instead of reusing a tarball that no longer exists in object storage.

Where to read more