Troubleshooting Jason

Work that has stopped is not always work that has broken. Most of the time the runtime is doing what it was told: waiting for a moment that has not arrived, waiting for a person who has not answered, or refusing work it cannot route. This skill is how to tell those apart from a genuine failure, and how to name the one repair that is safe rather than the first one that comes to mind.

Status: draft. No agent host has read this text in the state it ships in. Its commands parse against this build, because every skill's do. It covers what this build records and nothing else.

Look here first, in this order

Before any jason doctor — the dry run included — run these four readings, in this order. A diagnostic file is for what they cannot explain, and you cannot know that before you have read them. Each one can end the investigation on its own, and each one makes the next easier to read.

Is the runtime answering at all? If it is not, nothing anywhere is being claimed, and every item in the installation looks stuck for the same reason.

jason runtime status --human

The item itself — its status, its error code, how many attempts it has had, and which profile it ran under. The code is the answer; everything below is how to read it.

jason workitem get wi_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --human

The rest of the campaign, because one item stopping and every item stopping are different problems with different repairs.

jason workitem list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --status failed --status expired

The chronicle, which is what happened and in which order — claims, attempts, outcomes, reloads. It is the only reading that shows you a sequence rather than a snapshot.

jason journal list --work-item wi_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --human
jason journal list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --since 2026-09-18T09:00:00Z

A line's kind says what it records. jason journal kinds lists every kind the runtime reserves for its own lines, each with what it means and what it carries; read it when a line names a kind you do not know, rather than guessing from the name.

jason journal kinds --human

When a notification brought them here. A person may arrive because a notification said protective actions failed in campaigns it names by id. The failed and expired work items of those campaigns are the subject: the third reading above, once for each id it names, and without --campaign when it says there are more. Each item it lists is then read as this skill reads a failed item. The four readings are binding here too, before anything else; here the third comes before the second, because it is what names the items.

Three further readings answer the states a work item alone cannot tell you about: what is parked on a person's decision, what question a role has asked and nobody has answered, and what somebody has told Jason about an effect produced outside it.

jason approval list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD
jason decision list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD
jason report list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --human

The twelve states

Twelve things "it is stuck" turns out to mean. Decide which one you are looking at before you say anything to anybody: five of them are not failures at all, five of them nobody can fix from a session, and only two are about the work you asked for.

The codes named below are the common ones, not all of them. The runtime publishes more than two dozen attempt error codes, and one you do not find here is not a code that means nothing — read what it says, and if it names something to change, that is the answer.

A refusal recorded ambiguous is state 8 first, whatever its code. While an earlier attempt of a send may have reached the person, the claim refuses a repeat under the code of the state it would name alone — a missing route, a suppressed value, arguments to correct, an argument the route does not take — and records it ambiguous and final, its message saying that an earlier attempt of this work item may have reached the person. What those states say of themselves — nothing started, nothing attempted, nothing spent or done, a corrected new item as the repair — is true of the refusal, not of the attempt before it. Nobody creates the send again, corrected or not, until the provider has said the earlier attempt did not act.

1. Waiting for its time

How you recognise it. The status is created and the dispatcher would not claim it: a not_before or a retry_after is still in the future, or a due_at has already passed and the item can now only expire.

jason workitem list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --status created --not-eligible

What it means. Nothing is wrong. The item is doing what it was asked to do, and the runtime will claim it when the moment arrives. Say when that is, and stop.

2. Paused or archived

How you recognise it. The item looks perfectly healthy and is never claimed — and the campaign it belongs to is not active. Only an active campaign's work is claimed, with one exception: a paused campaign still lets through a provider_op item whose operation declares dispatch.in_paused_campaign: runs (optout.record, campaign.pause and message.cancel). So an archived or still-draft campaign holds every one of its items at once, and a paused one holds every item but theirs.

What it means. This is about the campaign, not the item, which is why reading the item over and over tells you nothing. Somebody paused it, or it was never started. Say which campaign and in which status; the person decides whether it should be running.

3. Awaiting a person

How you recognise it. The item's status is awaiting_approval, or there is a pending decision the campaign is waiting on. No attempt was made and nothing reached a provider.

What it means. This is not a failure and there is nothing to repair. An operation whose contract says a person must confirm it parks at the claim, and a question a role could not answer waits the same way. It moves when a person decides, and a session must not decide for them. Presenting what is waiting is approvals-and-questions.

4. Missing configuration

How you recognise it. The error code is one of no_route, profile_not_found, profile_disabled, profile_revision_refused, host_not_available or role_skill_invalid. To see where one operation would go for one campaign, and why it goes nowhere:

jason route resolve --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --operation campaign.enroll --human

What it means. Nobody's work item will fix this. Somebody must configure something — install a plugin, write a route, enable a profile, make an agent host available, correct a role's skill — and that is an operator's deliberate act. Nothing was started and nothing was spent — except where host_not_available says the host ran and answered that it is not signed in: the child started and stopped there, and the repair is the person's own, signing in to that host on this machine under their own plan. Name what is missing and hand it over; setting it up is operating-the-installation. For profile_revision_refused the profile exists but its current revision holds a word this build refuses: read the profile's problems with jason profile get <name>, then change it with jason profile update.

Not this state, but a repair of the same kind, the person's own: on antigravity_cli, executor_exited after the host exited 0 means the role was denied the call that reports. Each run carries a workspace hook that approves it (the first route, built from the host's pages and not yet run on an account); if the role is refused anyway, the fallback is the person's own command(<cli word>) permission rule in ~/.gemini/antigravity-cli/settings.json (on Windows shells the rule is command(regex:<cli word> .*)). The attempt is retried, and each retry meets the same denial. Jason cannot write that rule; the person adds it, with read_file(<harness folder>) beside it for the memory files.

5. The person is on the do-not-contact register

How you recognise it. The error code is suppressed, on an operation that reaches somebody.

jason suppression list --human

What it means. That channel value is on the do-not-contact register, so this campaign does not reach them there. Nothing was sent and nothing was attempted at the provider — the register is consulted before any of that — and this is the register working. It is final by design: the item is finished, and a second item for the same person on the same value would stop in exactly the same place.

The repair is not yours. Lifting a suppression is jason suppression remove, and it is a person's act on another person's behalf — somebody asked not to be contacted, and a session that lifted that to get its work moving would be the one failure in this whole document that reaches a real person. Say who is suppressed and on which value, and let the person decide. If the campaign should reach them somewhere else, that is new work on a channel they have.

6. A transient failure

How you recognise it. The failure was classed transient, and the item has been tried more than once. The attempt count on the item says how often; the chronicle says when.

What it means. Usually the provider was unreachable or busy. Sometimes the moment was the runtime's own and no provider was asked anything: at the claim, a schema check did not finish in time, and the attempt ended validation_timed_out — which, despite its name, found nothing wrong with the item, so it is not state 7. Either way the runtime already knows, retries it the same way, and decides when to try again and when to stop trying. There is nothing for you to do while attempts remain. Report how many there have been and what the last one said, and leave it to run. The same code classed ambiguous is state 8: there the answer, not the item, went unmeasured, after the provider had acted.

7. A permanent or validation problem

How you recognise it. input_invalid, or a failure the plugin classed permanent or validation.

Three spellings to expect yourself to get wrong while you look. A campaign id is an argument, not an option: it is campaign list-contacts cmp_…, and campaign list-contacts --campaign cmp_… is refused — which is the one every session so far has reached for first. The campaign's own people, each with where they stand in it, are that verb, and its enrolled is Jason's own membership, never enrolment at the provider; contact list --campaign cmp_… lists the ones not excluded. And these listings print JSON already, so there is no --json; --human is the option that changes the rendering.

What it means. The arguments do not satisfy the operation's published contract, or the provider refused them outright. This is final by design, and it is final because asking again with the same arguments would fail in the same way. The operation's own document is what the runtime enforces, and it is published with the project's source under docs/contracts/operations/; no verb prints one, so on a machine with no copy of the source, ask the operator for it rather than guessing at the correction.

One permanent code is about neither the arguments nor the account: capability_not_offered is classed permanent as well, and is state 12.

One validation code is about the provider's own object rather than the operation's arguments: provider_input_invalid says the plugin could not read the provider object the item carries beside its arguments in context.input, and refused it before any call. Its message, in the item's last_error.message, names the shape the plugin reads, or what in the object it cannot take, and never quotes what was given, and the provider's own skill teaches what goes there. The role that wrote the object corrects it on its next attempt: a corrected new work item, with the object in that shape.

A failure classed blocked is final too, and its repair is elsewhere. Its code is provider_blocked: the provider refused the account, or one sender under it, rather than this item's arguments — money or a plan, an allowance it counts, a key it no longer accepts, a channel disconnected or paused — and did nothing for the call. last_error.block on the item says what is blocked (scope, and sender_external_id when it is one sender), why (reason), where a person goes to clear it (link), and, where the provider said, when it may clear by itself (clears_at). Read those to the person. The repair is theirs, at the provider — topping up, reconnecting, renewing a key, or waiting for an allowance to renew — and never an edit of the item; once the block has cleared, the work is proposed again. Work a block holds does not end here: it waits on the block, which is state 11.

8. An attempt that was interrupted

How you recognise it. The failure was recorded as ambiguous. So is a refusal whose code names another state, classed ambiguous, whose message says that an earlier attempt of this work item may have reached the person: the claim refused to repeat a send that may already have gone.

What it means. It means exactly one thing: nobody can say whether the provider acted. The attempt was cut off somewhere between sending and hearing back, or its answer could not be measured, so the effect may have happened, may have half happened, or may never have started. Where the operation's contract declares a recovery read, the next attempt asks the provider what actually happened before it writes anything. Where it does not, the work stops there and a person decides — because the alternative is sending the same message to the same human being twice.

9. An effect reported from outside

How you recognise it. A report against the campaign says something was already done — through a provider's own tools, or by hand, or because the managed path was not available.

What it means. It is somebody's word that an effect occurred, and nothing else: nothing was approved, routed, supervised or verified. It moves no work item, closes nothing, and explains no failure. It is context for the person reading, and it may be the reason a second attempt would be a duplicate. Telling Jason about such an effect is reporting-outside-effects.

10. An outdated or unavailable plugin

How you recognise it. plugin_unavailable, or a plugin that lists problems of its own.

jason plugin list --human

What it means. The package is there and the program it needs is not — missing, not executable, or a version that does not answer. Such a plugin loads as unavailable rather than rejecting the whole snapshot, so everything else keeps working and only its operations stop. The listed problem names what is wrong on the machine. jason status names such a plugin, with its problem codes, in its optional plugin_availability check, and an unavailable notification plugin delivers nothing.

11. Waiting

How you recognise it. The status is waiting: a run of the item raised other work and ended by waiting for it, for a moment, or both. Its wait block says on which items, whether all of them or any one, and until when. A park on a provider block reads as this same waiting state with its block named, not as a state of its own.

jason workitem get wi_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --human
jason workitem list --campaign cmp_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --status waiting --human

What it means. Nothing is wrong, and the item is not holding anything up: while it waits it holds no slot, and the work it waits for is claimed like any other. The runtime starts it again by itself when that work has ended, when the moment it named comes, or when the wait's deadline does, whichever is first. If it seems to wait too long, look at what it waits for — an item there may itself be in one of the states above. There is no repair while the wait holds: do not cancel it to unstick it, and do not create its work again. Where the person decides it has waited enough, they end the wait themselves, and the item is started again with what is there:

jason --actor human:ada workitem resume wi_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --reason "the replies in are enough to decide"

A park on a provider block has a repair, and it is the person's. Its wait names the block under blocked_by — provider_block_id, scope and reason — and waits on no item and no moment, and its last_error is provider_blocked, whose block says what is blocked, why, the link where a person clears it and, where the provider said, clears_at. jason block list shows every open block, how many items each holds and its link; block get reads one block, and workitem list --block names the items it holds:

jason block list --human
jason block get blk_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --human
jason workitem list --block blk_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --human

The provider refused the account, or one sender under it, and not this item, so the person repairs it: they fix the cause at the provider, through the link, and the block's trial then lets one item through: acts first; where none can run, one held control, whose answer decides nothing but blocked. Once the provider takes an act, the block clears and releases everything it held. Where the person knows the cause is gone, they clear the block themselves, under their own name, and the next scan releases what it held:

jason --actor human:ada block clear blk_01JB6K8TQ2W9V4MZ0C3Y7H5NRD --reason "the card on the account was renewed"

A clear is their word that the cause is gone, not a mute, and where the provider still refuses, the next call opens a new block. Do not cancel, recreate or resume a parked item: the block releases it by itself, and the same work, asked again or resumed, parks on the same block.

A budget hold is the claim's own wait, and no run stands behind it. Launches:MaxPerDay:<role> limits how many runs of a role one campaign starts in a UTC day, and the item that would start one more is held, not failed, before any attempt. It reads as this same waiting state: its wait is the next 00:00Z, its last_error is launches_spent, whose message names the setting, and its workitem_waiting line in the chronicle says held_by with the code, the limit and the role. A notification counts it among the items that wait on a budget, and the campaign's other work goes on. There are three ways out: at 00:00Z the runtime releases the item by itself and counts the new day, so a day already spent by then holds it again; a person resumes that one item under their name, as above, and it goes past the limit with its run counted like any other; or a person raises the setting, which applies from the next scan to work not yet held, while an item already held keeps its moment. It keeps its due date and expires by it like any waiting item. Do not cancel or recreate it: it is not stuck, and the same work asked again counts against the same day.

12. A capability the provider does not offer yet

How you recognise it. capability_not_offered, classed permanent. The item is failed, and the message names what is not offered: the operation, or the one argument of it the provider does not take.

What it means. The plugin knows how to ask, and the provider does not offer what was asked yet: its API has no route for the call, or does not take the argument. Nothing was done there. It is final like state 7, but no correction of the arguments gets past it, and it is nobody's configuration: no route, grant or setting changes what the provider offers. Asking again meets the same answer, and nothing in the runtime falls back to something else. How a plugin tells is stated once in the contracts README (docs/contracts/README.md), beside the list of capabilities a provider may lack for a while.

What to do instead is a decision about the work, not a repair of the item — in a managed campaign, the manager's. Report what is not offered, in the message's own words, and that nothing was done. Once the provider offers it, the same work asked again as a new item goes through.

When a plugin that subscribes to the journal is behind or failing

Not a state of a work item, so not one of the twelve: a subscriber is handed journal lines after the runtime wrote them (docs/plugins.md §17), and what it does with them is nobody's work item. Read where each subscribed kind stands, then the chain's record, and only then say anything.

jason subscription list --human
jason subscription runs --kind workitem_failed --human
jason journal list --kind subscription_failed --human

• waiting_on names a plugin. The kind is waiting, not failing: a member of its chain loaded unavailable and the kind stays at its line until a reload makes it available or takes it out of the chain. Nothing is written for it. Read why the plugin is unavailable as state 10 does, then jason plugin reload.
• A subscription_failed line. It is the lasting record of one chain that ended at one handler for one line: {kind, line, plugin_id, class, code, attempts}, never the envelope or the failure's message. transient is tried again by the runtime up to its limit before the line is written; every other class ends the chain there, and the kind moves on to its next line. The code is the handler's own, a host rule's (a refused host, docs/plugins.md §9) or the protocol's, so say whose it is before explaining it; the plugin's README explains the plugin's own. jason subscription runs --kind <kind> shows each handler's outcome for the chains of that kind, newest first; those records are kept by count for each kind, so an old one may be gone while its subscription_failed line stays.
• A line handed twice. Delivery is at least once: after a restart a chain runs again from its first handler, and a handler that was handed the line before sees attempt above 1, as it does after a transient retry (attempt counts that plugin's own earlier entries for the line in the chain's record, plus one; a rewind opens a new chain, which counts from 1 again). That is the contract, not a fault, and it is the subscriber's to tell a repeat by.
• A lag that does not shrink with nothing waiting. Say so and collect jason doctor; the diagnostic file carries the subscriptions' figures and never an envelope.

A rewind is a person's act. jason subscription rewind --kind <kind> (--line <jrn_id> | --since <moment>) moves a kind's cursor back so its chain hands lines again, to just before the named line (a line of that kind) or the first line written at or after the moment; it is refused without --actor human:<Name>, and never goes forward. A moment needs its offset (2026-11-05T09:00:00Z): one without is answered invalid at since, naming the form. A rewind may hand a line again that was already handled, and a subscriber causing an effect twice is the case to warn about first. It supersedes a chain in flight for that kind and writes its own subscription_cursor_rewound line. Offer it with that consequence and wait for the person; never run it to see whether it helps.

The repairs that are safe

Five. Nothing else on this list, and nothing off it.

A corrected new work item. The ordinary repair for state 7: read the contract, fix the arguments, ask again. When state 6 runs out of attempts the item fails final the same way, and the repair is the same work asked again as a new item once the provider is back; nothing in the arguments changes. It is no repair for state 12: the same work goes through as a new item only once the provider offers it.

Writing or fixing a route. The repair for no_route, and an operator's act rather than a session's.

Reloading the plugins, once a package has actually changed on disk. Every package is read again and the snapshot is swapped whole, or the old one is kept and the reason is printed.

jason plugin reload --reason "the package was updated"

Restarting the runtime, when the process itself is the problem rather than anything in it. What that does to work in flight is narrower than it sounds: a shutdown stops claiming, gives handlers up to ten seconds, and does not kill children that are still running — their leases are still good, and a survivor completes against the next runtime. An attempt that was only scheduled is released back to created and claimed again; an attempt already processing is left to the lease and the heartbeat to decide, and a provider_op whose answer was lost that way ends ambiguous, which is state 8 and waits for a person. So a restart recovers the queue; it does not un-lose an answer.

A restart is a stop you run yourself: ask first, as "Starting and stopping it" in operating-the-installation says.

jason runtime restart

Applying an update, when the installed version is the known cause. That is operating-the-installation.

What is not a repair

Do not retry blindly. The runtime already retries everything worth retrying, on its own schedule, and it counts the attempts. A failure it called final was called final for a reason — repeating it by hand produces the same failure, or worse, a second real effect on a real person.

A failed item is finished. It is not reopened and it cannot be retried by hand. If the work is still wanted, it is new work — work still wanted is new work, asked for again as a fresh item, its arguments corrected where they were wrong, with its own id, its own attempts and its own line in the chronicle. An item that merely expired is the one thing the runtime itself reopens: moving its due_at forward brings it back, because it never ran.

Deciding an approval, or answering a question on the person's behalf, is not a repair either, however obvious the answer looks. The runtime refuses a decision that does not name a person, and it is right to.

Editing anything under the data directory by hand — the database, the chronicle, a plugin package whose digest was already computed — is not a repair. The chronicle is append-only and enforced as such three times over, and a package whose contents no longer match its digest stops running rather than running differently.

What a useful report carries when it is none of these

When the twelve states do not explain it, the useful thing to produce is a description somebody else can act on, not a theory — and jason doctor collects the installation's half of it into one file, whether or not the runtime answers.

jason doctor --dry-run
jason doctor

Run the dry run first and show the person what it lists, because the file is theirs to share or not. It writes nothing; it lists what a plain run would write, and where. Then ask the person one question — may I write the file? — and stop. Offer no alternatives; a report written instead, or beside it, is not what they were asked about. The bundle holds the versions; whether the runtime answered and what it says about itself; the shape of the settings — keys, types and lengths, with a value only for the settings its own list names; the work items counted by kind and status, and the newest failures by their codes; recent errors and a bounded slice of the logs; and the chronicle's metadata — how many entries of each kind and when, never what they say.

What it leaves out is just as deliberate. What the runtime says about itself travels with a few free-text fields withheld, and the bundle names each one. A plugin, a role or a skill pack Jason does not ship travels as an alias — <plugin-1>, <role-1>, <skill-pack-1>, one per name — never by its own name. A skill source given with --source other than the public repository, and the ref it was taken at unless that is a release tag, travel as <skill-source>. The home directory, a data directory other than ~/.jason — this one, or another the runtime reports — the harness root, the folder the executable is in outside home, and the names of the account and the machine are rewritten before anything is written. It never carries the capability token, a request body or a prompt, and it reaches nothing beyond this machine. It writes one file and prints where; sending it anywhere is the person's act, never yours. --include-journal adds what the journal entries say: campaign names and fields as they changed, project names as they changed, the folders a project link recorded, campaign and work-item contexts as they changed, result formats, the addresses and numbers put on or taken off the do-not-contact register, the accounts a campaign's routes bind, the options decisions were answered with, the errors attempts ended with, provider identifiers, the verdicts roles recorded on replies and the decisions whose answers they carry, and the standing approvals people set: their categories, reactions, goals and limits, the effect, tool and operation a report names, the failure text and receipts notification channels reported, entries people and agents wrote themselves, the names actors gave, and the reasons they typed — so use it only when the person asks for it, and pass on the warning it prints.

After the file is written, jason doctor prints the address of the repository's problem form in its result and on stderr, as problem_report_url in the result, with the version and the platform filled in. Offer the person that link: opening the issue, with the file attached, is their act, never yours. A file made with --include-journal goes only to the support address the README gives under Getting help, never to an issue: an issue is public the moment it is submitted. With --include-journal, problem_report_url is null and the result's warnings say the file goes to the support address only; never offer an issue for it.

The bundle is not the report. It carries what the installation knows; the report needs four things it cannot know:

• what was asked for, in one sentence: which campaign, which operation or role, with which arguments;
• the work item id and its error code, exactly as printed;
• the relevant chronicle lines, in order, with their timestamps;
• what you have already ruled out, and how.

A guess about the cause is not one of them. Name what you observed; let whoever reads it decide what it means.

Logs are JSON Lines written under ~/.jason/logs/, and jason logs reads them without asking the runtime, so it answers the same when the runtime is stopped or will not start. It filters by level, campaign, work item and time, and returns the newest hundred events that match, oldest first, unless --limit says otherwise:

jason logs --level warning --since 2026-09-18T09:00:00Z
jason logs --work-item wi_01JB6K8TQ2W9V4MZ0C3Y7H5NRD

Read them when the readings above have not settled it. They never contain request bodies, prompts, work-item contexts or the capability token, so do not send somebody to the logs expecting to find what was actually sent to a provider — it was never written there.