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

# A step can end in a way the workflow does not handle

> A step whose operation can end partial has no default route, so the workflow stays unready until its author says what happens then.

Troubleshooting · workflows

> **Use when**
>
> "`penumbra workflows check` prints `unhandled_outcome`, or a publish is refused with `workflow_invalid` and that problem in its list."

> **Looking for something else?**
>
> A step that names an operation the catalog does not list (problem [A step names an operation this project cannot use](https://docs.pnbr.io/troubleshooting/workflow-step-unavailable.md)). A value of the wrong type or a reference to a later step (card rule workflow\.3).

## Signs

* `penumbra workflows check --file <workflow.json>` exits with code 3. It prints
  a line that starts `extract.on: unhandled_outcome`, with the step and the
  `on` map, and ends `(expected a route for partial, received none)`.
* A publish is refused with `workflow_invalid`, and the same line is in the
  list under it.
* A draft saved with `create` or `update` shows the problem under `problems:`.

## Why it happens

Every operation declares the ways a call can end: `succeeded`, `partial`,
`no_effect`, `refused` and `failed`. A workflow routes each one. Four have a
default. A success continues, and a step with no effect skips what depends on
it. A refusal stops the workflow, and a failure stops it with no retry. A
partial result has none. Only the person knows whether what landed is enough, for
example a run that read some of the Files.

## What Penumbra does

By itself:

* Lists each unrouted outcome as `unhandled_outcome` with the step and the path
  to its `on` map.
* Refuses to publish a draft that has the problem.
* Lets you save the draft with the problem so you can keep editing it.

You must:

* Ask the person what should happen when only part of the work landed.
* Write that answer as a route in the step's `on` map.

Not handled:

* Penumbra does not choose a route for you, and it does not warn when a route
  you chose hides a failure.

## Do

1. Run `penumbra workflows catalog --step <operation>` and read the outcomes of
   the step. It describes each one.
2. Ask the person what should happen after each outcome you must route. Say what
   landed in that case, for example "some of the Files were read".
3. Add the route to the step's `on` map. A route is one of `continue`, `end`,
   `stop` or `skip_dependents`, or `{ "retry": 1, "then": "continue" }` with a
   retry count of at most 3.
4. Run `penumbra workflows update <workflow> --file <workflow.json>`, then check
   again.

## Don't

* Don't route `partial` to `continue` to make the problem go away. Ask first.
* Don't remove the step to avoid the question.
* Don't publish a draft that still has problems and expect the publish to
  warn. It is refused.

## Check

* `penumbra workflows check --file <workflow.json>` prints `No problems.` and
  exits with code 0.
* `penumbra workflows publish <workflow>` makes a version.

## Related

Card [workflow](https://docs.pnbr.io/concepts/workflow.md), with rules [workflow.2](https://docs.pnbr.io/concepts/workflow.md#rule-workflow-2) and [workflow.4](https://docs.pnbr.io/concepts/workflow.md#rule-workflow-4). Recipe
[automate-a-job](https://docs.pnbr.io/guides/automate-a-job.md). Problem [workflow-step-unavailable](https://docs.pnbr.io/troubleshooting/workflow-step-unavailable.md).

## Keep going

[Workflow](https://docs.pnbr.io/concepts/workflow.md) · [Write a job as a workflow](https://docs.pnbr.io/guides/automate-a-job.md) · [A step names an operation this project cannot use](https://docs.pnbr.io/troubleshooting/workflow-step-unavailable.md) · [Extraction](https://docs.pnbr.io/concepts/extraction.md)

Penumbra Grammar 0.6.26


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.