Skip to main content

​
The stream stopped but the run didn’t

The progress stream times out after 300 seconds. The run keeps going.
Long-running agents are expected to outlive the stream. Rejoining tells you the current state.

​
The run is waiting on a person

A run that needs information it can’t infer raises an input request and pauses rather than guessing.
Read the request before submitting — it names the fields and what each expects. When an agent has exactly one open request, address it by agent instead of by id:
Submitting to a request that is already satisfied, cancelled, or expired is rejected rather than ignored.

​
A story failed

What happens after a failure depends on the step’s error policy.
A run can complete with a best-effort failure inside it. “Completed” is not the same as “everything worked” — check the stories, not only the run status.
If the policy is wrong for the step, that’s a spec change, not a run problem. Resume the plan chat and adjust it.

​
The agent can’t reach something it needs

Readiness reports per-skill blockers and exits non-zero when any exist. It answers a different question from conformance: not “is the package well-formed” but “can it actually execute here”. Many blockers have a targeted, idempotent fix:
Available actions: reconcile, introspect, refresh-tools, fix-credential, verify-backend.

​
A scheduled run never fired

Check the schedule itself:
Three things to look at. Next fire. If it’s further out than you expect, the expression isn’t what you meant. All schedules are evaluated in UTC — 0 9 * * * is 09:00 UTC, not 09:00 local. Environment. If it says dry_run and you expected live, set reverted it. set sends the run mode on every call and defaults it to dry_run, so changing only --cron drops a live schedule back:
Last fired. A — means it has never fired. If the schedule was set after the day’s fire time, the next run is the next future occurrence — changing a schedule resets its clock and never back-fires. If the platform was down across several scheduled times, it fires the most recent missed one once on recovery, not a burst.

​
A webhook fired but no run started

The event record distinguishes three different problems: the delivery never arrived, it arrived and was rejected, or it arrived and started a run that failed. If nothing is recorded at all, the delivery isn’t reaching JoyStream. Confirm the URL and secret in the source system:
triggers test signs with the real secret on the server, so it exercises the true signature path. If the test works and real deliveries don’t, the mismatch is in the source system’s configuration. Also check the binding is enabled:

​
The run happened but the result is wrong

This is the failure mode worth the most attention, because nothing errors.
Compare the output against the acceptance criteria in the spec. A run that completed while producing the wrong answer is a spec problem, not a runtime one — the boundaries or the success criteria didn’t capture what you meant. The fix is a new spec version. Resume the plan chat, refine it, commit, build, and dry-run again.

​
The run used the wrong mode

Without --mode, a run uses the agent’s current deployment stage. A live-staged agent runs live.
To take an agent out of production entirely:

​
Seeing more

--verbose shows an output preview for each step. JOYSTREAM_DEBUG logs the full traceback to stderr.

​
See also