Handle failures

version: 2
identifier: changes_since
name: Changes since
description: The commits merged since a git ref.
input_schema:
  type: object
  required:
  - base
  properties:
    base:
      type: string
      description: The ref to start after, such as a release tag
steps:
- id: commits
  tool_name: github__tool__git_log
  input:
    base: '{{input.base}}'
    head: HEAD
finish:
  output:
    count: '{{commits.count}}'
    latest: '{{commits.commits.0.subject}}'

version: 2
identifier: changes_since
name: Changes since
description: The commits merged since a git ref.
input_schema:
  type: object
  required:
  - base
  properties:
    base:
      type: string
      description: The ref to start after, such as a release tag
steps:
- id: commits
  tool_name: github__tool__git_log
  input:
    base: '{{input.base}}'
    head: HEAD
finish:
  output:
    count: '{{commits.count}}'
    latest: '{{commits.commits.0.subject}}'

changes_since returns how many commits landed since a git ref, and the newest one’s subject.

version: 2
identifier: changes_since
name: Changes since
description: The commits merged since a git ref.
input_schema:
  type: object
  required:
  - base
  properties:
    base:
      type: string
      description: The ref to start after, such as a release tag
steps:
- id: commits
  tool_name: github__tool__git_log
  input:
    base: '{{input.base}}'
    head: HEAD
finish:
  output:
    count: '{{commits.count}}'
    latest: '{{commits.commits.0.subject}}'

Every failure below exits with code 1 and names the cause on stderr.

A tool fails

Pass a tag that doesn’t exist:

graph plan run changes_since \
  --input base=v9.9.9

The error names the step, the tool, and what the tool printed:

✗ github__tool__git_log 14.3ms
Error: plan failed at step commits (github__tool__git_log): {"error":"'bash' exited with exit status: 128","stderr":"fatal: bad revision 'v9.9.9..HEAD'","stdout":""}

Fix the input and run again.

A template points nowhere

With a typo in the finish, '{{commits.comits.0.subject}}', the step runs and the plan fails when it fills the template:

Error: failed to render plan output: bad path 'commits.comits.0.subject': no key 'comits' at commits (available: commits, count, total, truncated)

A bad path is a mistake in the plan. The error lists the keys that do exist, so fix the template.

The data runs out

Pass the current commit, so there’s nothing to list:

graph plan run changes_since \
  --input base=HEAD

The plan is right, but commits.commits is empty, so there’s no first subject:

Error: failed to render plan output: empty data at 'commits.commits.0.subject': commits.commits is an empty array

End cleanly when there’s nothing to do

Add an exit step after commits. When the count is 0, it ends the plan as a success and returns the same keys as finish.output:

.graph/plans/changes_since.yaml

- id: nothing_new
  tool_name: exit
  input:
    when:
      value: '{{commits.count}}'
      op: eq
      to: 0
    status: success
    message: No commits since {{input.base}}.
    output:
      count: 0
      latest: none

Run it again with base=HEAD. It exits with code 0:

{
  "count": 0,
  "latest": "none"
}
✓ No commits since HEAD.

Debug a plan

Pause a run and inspect the input a step gets.

Stop early with exit gates

End a plan early on other conditions.

Iterate with map and reduce

Keep going past items that fail.

Run a plan

Run a plan with inputs and use its result.

Getting started

Agents

Plans

Tools

Packs

Integrating

Reference

Handle failures

A tool fails

A template points nowhere

The data runs out

End cleanly when there’s nothing to do

Debug a plan

Stop early with exit gates

Iterate with map and reduce

Run a plan

​A tool fails

​A template points nowhere

​The data runs out

​End cleanly when there’s nothing to do

​Related guides

Debug a plan

Stop early with exit gates

Iterate with map and reduce

Run a plan

A tool fails

A template points nowhere

The data runs out

End cleanly when there’s nothing to do

Related guides