Troubleshooting

Start here when you do not know which part is at fault. Each area's fixes live at the end of its own page — the table routes you there — and the one symptom that can come from anywhere, a dispatch that will not go, is told apart below. The last two sections show what to collect and where to send it.

Where the fixes live#

The symptom	Where the fix lives
The runner never appears, is offline, or the service crash-loops	Manage the runner fleet
A pack or an action is missing from the catalog	Roll out and roll back packs
A run failed, timed out, or looks stuck	Runs
The LLM client or the bridge misbehaves	Connect a CLI agent
Sign-in fails, or members loop back to the provider	Single sign-on
Provisioning or group sync is stale	Directory sync
The audit export stalls, repeats events, or errors	Audit & SIEM

An action will not dispatch#

Dispatch from Runners first, even if the agent is what failed. The run row shows which gate stopped it — faster than reading the same error secondhand through the agent.

What you see	What stopped it	Where it is fixed
The runner or action is visible, but cannot be selected	Runner or pack access does not allow this target. Ask an administrator to review your access.	Teams & access
Dispatch is refused before a run appears	Pack trust. A pending or drifted content hash is not dispatchable, by design.	Roll out and roll back packs
The run lands Denied	Policy. The matched rule and its reason are recorded on the run.	Policies & approvals
The run sits awaiting approval	Policy asked for a person. It waits for an approver. A denial cancels it.	Policies & approvals
The run lands Refused	The runner rejected it on a pre-execution check — a pack-hash mismatch, a signature problem, or local admission. Nothing executed.	Signed dispatch
The run lands Error without reaching the host	The runner was offline, disabled, or removed, or never acknowledged the send before the dispatch timeout.	Runner fleet

Over MCP, a stale or hidden target comes back as target_contract_changed with the exact refresh call — follow that refresh once, then retry once. signature_required lists the runners that require client signing, and not_allowed means the current scope does not permit the request — it is not permission to probe.

On Team or Enterprise, contact support when policy allows the action, its trusted hash is current, the runner is online and in scope, and dispatch still refuses with no matched rule on the run.

Collect this before you contact support#

Reports with this evidence usually need one response. Reports without it can cost a day of questions.

— Versions of every component involved — the runner (emisar --version), the bridge (emisar-mcp --version), and the LLM client.
— The UTC time window in which it happened, not "this morning".
— Safe labels, not secrets — the runner name and group, and the account name. Never the enrollment key, the runner token, an API key, or a signing key.
— The identifiers — the run id, the operation id, the request id, and for a key problem the key id (Copy ID on its row in AI agents). They are how we find the same event you are looking at.
— sudo emisar doctor output from the affected host, whole rather than the one line you think matters.
— A bounded slice of the logs around the window — sudo journalctl -u emisar -n 200 and sudo emisar events tail --lines 100. A whole journal is harder to read, not more complete.
— The exact error text and whether it reproduces — every time, sometimes, or once.

Redact before you send.

Never paste a raw token, key, or certificate into a support request, ticket, chat message, or run reason. The runner redacts action output before it leaves the host, but provider output you copied by hand has not passed through that redaction — read it before attaching it and mask anything that looks like a credential. If a secret is already exposed, treat it as an incident, not a support request. Go to Security incidents.

Where to send it#

— A product problem on Team or Enterprise goes to Support with the evidence above. This includes anything broken, unclear, or slower than expected. Free is self-serve; use the documentation linked above.
— A suspected compromise or a vulnerability goes to security@emisar.dev. Examples include a leaked credential, an unexplained action, or an unexpected content hash. Security incidents lists the containment steps. Contain first. Send the report within the hour.

← Previous

Runbooks

Security incidents