Skip to main content
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). 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.
Card workflow, with rules workflow.2 and workflow.4. Recipe automate-a-job. Problem workflow-step-unavailable.

​
Keep going

Workflow · Write a job as a workflow · A step names an operation this project cannot use · Extraction