Debug Shell Script Whitespace Problems

Shell Scripts and Invisible Characters

Shell scripts are particularly sensitive to invisible characters because the shell interpreter treats them as part of commands, arguments, and control flow. A single misplaced invisible character can turn a working script into one that produces baffling errors.

The Classic CRLF Problem

The most common shell script whitespace issue is CRLF line endings:

#!/bin/bash\r    # \r is invisible but present
echo "hello"\r   # bash sees: echo "hello"\r

Errors you'll see:

• /bin/bash^M: bad interpreter: No such file or directory
• \r: command not found
• syntax error near unexpected token

BOM in Shell Scripts

A BOM at the start of a shell script makes the shebang invalid:

[BOM]#!/bin/bash     # kernel can't find the interpreter

The BOM is three bytes (EF BB BF) that the kernel reads before the #!, causing the script to fail on execution.

NBSP in Commands

A non-breaking space in a command looks correct but isn't:

apt-get install nginx    # NBSP: "apt-get install" is not found
if [ -f file.txt ]; then  # NBSP in test brackets

Trailing Whitespace in Variables

PORT=8080·     # Trailing space: PORT is "8080 " not "8080"
curl http://localhost:$PORT/api  # Tries port "8080 " — fails

Debugging Workflow

1. Paste your script into the Whitespace Visualizer.
2. Check Line Endings: Should show "LF (N)" only. Any CRLF must be converted.
3. Check for BOM: Look for [BOM] at the very start.
4. Check for NBSP: Scan for ° markers, especially in commands and paths.
5. Check trailing whitespace: Look for · markers at line endings.
6. Clean all offending characters and copy the fixed script.

Prevention

• Set your editor to use LF line endings for .sh files
• Add to .editorconfig: [*.sh] end_of_line = lf
• Add to .gitattributes: *.sh text eol=lf
• Use shellcheck to catch common script issues