GitHub Actions "Argument list too long" from a Large Matrix or Command

By Daniel Zoghalchali·Latchkey

A command was invoked with more arguments than the operating system allows. On a runner this usually comes from expanding a large matrix value or a giant file glob directly onto a command line.

What this error means

A run step fails with "Argument list too long" (errno E2BIG). The command itself is fine; the problem is the total size of the argument list passed to it.

/usr/bin/bash: line 1: /usr/bin/find: Argument list too long
# or
bash: ./tool: Argument list too long

Common causes

Huge expanded value on the command line

Interpolating a large matrix entry, a long JSON blob, or thousands of filenames directly into a command exceeds the kernel ARG_MAX limit.

Glob expands to too many files

A shell glob (e.g. process *.json) that matches tens of thousands of files passes them all as arguments and overflows the limit.

How to fix it

Pipe arguments instead of inlining them

Stream the list via stdin or xargs rather than placing every item on the command line.

- run: |
    find src -name '*.json' -print0 | xargs -0 -n 100 ./process
# or feed a file list
    git ls-files '*.json' | ./process --from-stdin

Reduce what is passed at once

1. Shard a large matrix so each leg handles a smaller slice.
2. Write big values to a file and pass the file path, not the contents.
3. Use xargs -n/-L to batch arguments under the OS limit.

How to prevent it

• Pass large inputs via files or stdin, not inline arguments.
• Batch with xargs when processing many files.
• Shard large matrices so no single command is overloaded.

Frequently asked questions

Related guides

References

• GitHub Actions documentation
• Workflow syntax for GitHub Actions