> ## Documentation Index
> Fetch the complete documentation index at: https://docs.joystream.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Blocked or failing runs

> A run that stopped, stalled, never started, or finished wrong — how to find out which, and what to do.

## The stream stopped but the run didn't

The progress stream times out after 300 seconds. The run keeps going.

```bash theme={null}
jstm agent run show failed-payment-digest/runs/12
```

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.

```bash theme={null}
jstm input-requests list --status open
jstm input-requests show 9b74e2a1-33cd-4f80-a5e6-1d20b8f7c4aa
jstm input-requests submit 9b74e2a1-… --values '{"approver":"dana@acme.com"}'
```

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:

```bash theme={null}
jstm input-requests submit failed-payment-digest --values '{"approver":"dana@acme.com"}'
```

Submitting to a request that is already `satisfied`, `cancelled`, or `expired` is rejected rather than ignored.

## A story failed

```bash theme={null}
jstm agent run show failed-payment-digest/runs/12
jstm agent stories failed-payment-digest --status failed
```

What happens after a failure depends on the step's error policy.

| Policy        | Behavior                                           |
| ------------- | -------------------------------------------------- |
| `CRITICAL`    | The run aborts                                     |
| `MUST_HAPPEN` | Retries with backoff, then aborts if still failing |
| `BEST_EFFORT` | Records the failure and continues                  |

<Warning>
  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.
</Warning>

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

```bash theme={null}
jstm agent readiness failed-payment-digest
```

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:

```bash theme={null}
jstm agent readiness-fix failed-payment-digest --action reconcile
jstm agent readiness-fix failed-payment-digest --action refresh-tools --server endpoint/acme/ledger
jstm agent readiness-fix failed-payment-digest --action fix-credential --skill google-calendar-read
```

Available actions: `reconcile`, `introspect`, `refresh-tools`, `fix-credential`, `verify-backend`.

## A scheduled run never fired

Check the schedule itself:

```bash theme={null}
jstm agent schedule show 8c41f2b9-77de-4a30-b0c5-2e1f6a9d4b77
```

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:

```bash theme={null}
jstm agent schedule set 8c41f2b9-… --cron "0 9 * * 1" --env live
```

**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

```bash theme={null}
jstm triggers events --binding-id 3f21b8c0-91ad-4f6e-89b2-77c0a4e1d9f3
jstm triggers event 7ac1d3f5-…
```

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:

```bash theme={null}
jstm triggers webhook-url 3f21b8c0-…
jstm triggers test 3f21b8c0-…
```

`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:

```bash theme={null}
jstm triggers show 3f21b8c0-…
```

## The run happened but the result is wrong

This is the failure mode worth the most attention, because nothing errors.

```bash theme={null}
jstm agent run show failed-payment-digest/runs/12
jstm agent view failed-payment-digest --definition
```

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.

```bash theme={null}
jstm agent status failed-payment-digest
jstm agent run failed-payment-digest --mode dry_run
```

To take an agent out of production entirely:

```bash theme={null}
jstm agent dry-run failed-payment-digest --no-run
jstm agent schedule clear 8c41f2b9-…
```

## Seeing more

```bash theme={null}
JOYSTREAM_DEBUG=1 jstm agent run failed-payment-digest --verbose
```

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

## See also

* [Run an agent](/guides/run-an-agent)
* [Review runs and tickets](/guides/review-runs-and-tickets)
* [Agent inputs](/features/agent-inputs)