Error handling

Every command reports success or failure through its exit code. Scripts and CI jobs should branch on the exit code, not on the text a command prints.

Exit codes

Code	Meaning
`0`	The command succeeded.
`1`	The command failed, or an edit was refused. Details are on stderr.
`2`	The arguments were invalid. graph prints usage help to stderr.
`3`	`graph plan run` was missing an input, or an input didn’t match the plan’s `input_schema`. The schema is printed to stderr.
`4`	A plan’s `exit` step ended the run with `status: error`.

A tool that reports an error during graph tool test --json still exits 0: the call completed, and the result’s isError field says the tool failed.

Output streams

stdout carries only the command’s result: an answer, a plan’s output, a listing, or a --json envelope. Progress, warnings and error messages go to stderr. When graph refuses a request, such as an invalid plan or a rejected edit, --json still prints the envelope describing why to stdout before exiting 1. Other failures are reported on stderr only.

Machine-readable output and logs

enum<string>

How graph reports progress and failures on stderr. Unset, stderr is for people.

Value	Effect
`jsonl`	stderr becomes a stream of JSON events, one per line. `ask` steps can’t prompt anyone, so they use their `whenUnanswered` setting.
`github`	A failing `graph plan run` also prints a `::error::` annotation to stdout, which GitHub Actions shows on the run.

string

A log filter for stderr, such as info or graph=debug. -v, -vv and -vvv set info, debug and trace.

Go to full reference

Getting started

Agents

Plans

Tools

Packs

Integrating

Reference

Error handling

Exit codes

Output streams

Machine-readable output and logs

​Exit codes

​Output streams

​Machine-readable output and logs

​Related environment variables

Exit codes

Output streams

Machine-readable output and logs

Related environment variables