Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

GitHub Actions step fails writing to GITHUB_OUTPUT

ErrorError: Unable to process file command 'output' successfully.

Short answer

The runner reads GITHUB_OUTPUT line by line, and every entry must be name=value or a name<<DELIMITER block. A value with a newline, a stray line without an equals sign, or a block with no closing delimiter makes the step fail. Write multi-line values with a delimiter block and keep other text out of the file.

  • Applies to GitHub Actions, bash on ubuntu-latest
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read the red lines under the failing step. The text after 'Invalid format' is the exact line the runner refused, so it shows which of the causes below you have.

    # add temporarily to the failing step to see what is being written
    cat "$GITHUB_OUTPUT"
  2. 2Match what you see, then jump to its fix

    1. 1Invalid format followed by the second line of your value (for example the body of a commit message or a pretty-printed JSON).A multi-line value was written as name=valueFix
    2. 2Invalid format with a line of tool output, a warning or an error message instead of name=value.Other output ended up in the fileFix
    3. 3Invalid value. Matching delimiter not found 'EOF'The delimiter block is never closedFix

What does the error look like?

  • Error: Unable to process file command 'output' successfully.
  • Error: Invalid format '...'
  • Error: Invalid value. Matching delimiter not found 'EOF'

Cause 1 of 3

A multi-line value was written as name=value

1Check

The runner treats each line as its own entry, so any line after the first newline that has no equals sign is invalid. Command substitution with several output lines does this.

grep -n 'GITHUB_OUTPUT' .github/workflows/*.yml

2Fix

Use the multi-line format: name, then <<, then a delimiter, the value, and the delimiter alone on its own line.

- id: notes
  run: |
    {
      echo 'body<<EOF'
      cat notes.txt
      echo EOF
    } >> "$GITHUB_OUTPUT"

3Verify

A later step reads the whole value.

- run: echo "${{ steps.notes.outputs.body }}"

Confirmed by docs.github.com

Did this fix it?

Cause 2 of 3

Other output ended up in the file

1Check

Anything written to the file by mistake counts as an entry. This happens when a command that prints extra text is captured into a variable that is then echoed into GITHUB_OUTPUT, or when a tool is pointed at the file.

cat "$GITHUB_OUTPUT"

2Fix

Write only name=value lines. Capture the command into a variable first, check it, then write one clean line; send incidental output elsewhere.

version="$(node -p "require('./package.json').version")"
echo "version=$version" >> "$GITHUB_OUTPUT"

3Verify

The step succeeds and the output is available to the next step.

- run: echo "${{ steps.ver.outputs.version }}"

Confirmed by raw.githubusercontent.com

Did this fix it?

Cause 3 of 3

The delimiter block is never closed

1Check

A block opened with name<<EOF ends only at a line that is exactly EOF. If the closing line is missing, or the file ends without a final newline, the runner rejects it. The delimiter must also not appear alone on a line inside the value.

cat -A "$GITHUB_OUTPUT" | tail -n 5

2Fix

Always write the closing delimiter with echo so it gets a newline. For arbitrary content, choose a delimiter that cannot occur in the value, or write the data to a file and output its path.

delim="ghadelim_$(uuidgen)"
{
  echo "text<<$delim"
  cat result.txt
  echo "$delim"
} >> "$GITHUB_OUTPUT"

3Verify

Re-run the job; the step passes.

gh run watch

Confirmed by raw.githubusercontent.com

Did this fix it?

How do I stop it coming back?

  • Give the step an id, and write outputs in the form name=value with one echo per output.
  • Use a delimiter block for every value that can contain a newline, such as commit messages or JSON.
  • Keep values small; write large data to a file or an artifact and pass the path.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.