🚨 Bash Error Guide: '[: too many arguments' — Fix Unquoted Test Operands

Overview

Bash prints [: too many arguments (or [: <word>: binary operator expected) when a test / [ ... ] receives more words than its operator grammar allows:

./check.sh: line 9: [: too many arguments

Like every other [ failure, the cause is word-splitting. [ is a command; the shell splits its arguments before it runs. If an unquoted variable holds spaces, a multi-line value, or a glob that expanded, a two- or three-argument test suddenly gets four or more, and [ can’t parse it.

Symptoms

• A test works for simple values but fails when a variable contains spaces, tabs, or newlines.
• The message alternates between too many arguments and binary operator expected depending on where the extra word lands.
• Command-substitution operands ([ $(cmd) = x ]) break when cmd prints multiple lines.
• Filename tests ([ -f $path ]) fail when $path contains a space or when a glob matched several files.

Common Root Causes

• Unquoted variable with whitespace — [ $name = admin ] where name="john doe" becomes [ john doe = admin ] (four words).
• Multi-line command substitution — [ $(grep foo file) = bar ] when grep matched several lines.
• Unquoted glob — [ -f $dir/*.log ] expanding to multiple filenames.
• Combining tests without -a/-o correctly, or mixing [[ ]] grouping into [ ].
• A value that is itself several tokens injected from the environment or user input.

Diagnostic Workflow

Count the arguments [ actually receives:

name="john doe"
set -- $name = admin
printf 'argc=%d\n' "$#"      # argc=4  -> too many

Trace and grep the failing test:

bash -x ./check.sh 2>&1 | grep -n "too many\|'\['"

Reveal hidden whitespace or newlines in the value:

printf '%q\n' "$name"        # shows spaces/newlines escaped

Example Root Cause Analysis

A deploy gate compared the active git branch:

BRANCH=$(git branch --show-current)
if [ $BRANCH = main ]; then
  deploy
fi

In a detached-HEAD CI checkout it failed:

gate.sh: line 3: [: too many arguments

bash -x revealed the value wasn’t a single clean word:

+ BRANCH='feature/login fix'
+ '[' feature/login fix = main ']'
gate.sh: line 3: [: too many arguments

The branch name contained a space (feature/login fix), and unquoted it split into two arguments, giving [ four words. Quoting fixes it, and [[ ]] makes it bulletproof:

BRANCH=$(git branch --show-current)
if [[ "$BRANCH" == main ]]; then
  deploy
fi

With "$BRANCH" quoted, the whole branch name is one argument regardless of spaces, and the test evaluates cleanly to false.

Prevention Best Practices

• Quote every variable in a test — [ "$x" = y ]. Whitespace and newlines then stay inside one argument.
• Prefer [[ ... ]] in Bash — it treats an unquoted variable as a single word, so spaces can’t add arguments.
• Sanitize command-substitution output — capture, then check it’s a single line ([ "$(printf '%s' "$out" | wc -l)" -eq 0 ]) before comparing.
• Quote glob-bearing paths and avoid [ -f $dir/*.log ]; loop over matches instead.
• Validate external input early, rejecting values with unexpected whitespace.
• Run ShellCheck (SC2086) to flag unquoted test operands automatically.

Quick Command Reference

[ "$x" = "y" ]              # quoted operands: one word each
[[ $x == y ]]              # [[ ]] doesn't split on whitespace
set -- $x = y; echo "$#"    # count how many words [ receives
printf '%q\n' "$x"          # reveal spaces/newlines in the value
bash -x ./script.sh         # trace the real expansion
shellcheck ./script.sh      # SC2086 catches the unquoted operand

Related Guides

• Bash Error Guide: ‘unary operator expected’ — the opposite problem: an operand went missing instead of multiplying.
• Bash Error Guide: ‘integer expression expected’ — numeric tests fed a non-number.
• Bash Error Guide: ‘ambiguous redirect’ — the same word-splitting bug, but in a redirect target.

Conclusion

[: too many arguments is word-splitting turning a clean comparison into an over-long argument list — a variable with spaces, a multi-line command substitution, or an expanded glob. Quote every operand and prefer [[ ... ]] in Bash, so values stay single arguments no matter what they contain. Combined with ShellCheck in CI, this class of [ failure disappears from your scripts.