Zsh Syntax Error on macOS: How to Find and Fix

What a syntax error means

A syntax error in Zsh is a message from the interpreter that cannot understand a command or a line in a configuration file. The full error text usually looks like this:

zsh: syntax error near unexpected token `...'

or

zsh: parse error near `...'

Zsh points to the specific symbol (token) that caused the problem and often includes a line number if the error is in a file. This type of error occurs when starting the terminal, running a script, or typing a command manually.

Common causes

1. Typos in the command or configuration file — for example, a missing character or an extra space.
2. Incorrect use of quotes — unbalanced quotes (" or ') or their absence where required.
3. Unescaped special characters — characters like $, *, ?, [, ], (, ) can change the meaning of a command if not escaped with a backslash (\) or not enclosed in quotes.
4. Incomplete constructs — unclosed brackets, quotes, or code blocks (e.g., if ... then without fi).
5. Syntax conflict with Bash — if you copy commands or settings from Bash to Zsh, some constructs (like [[ ... ]] or arithmetic operations) may differ.
6. Corrupted configuration file — for example, .zshrc was modified incorrectly or contains remnants from other programs.

Method 1: Check the command or script

If the error appears when running a specific command or script, carefully review its syntax.

1. Copy the command that triggers the error.
2. Check that all quotes are balanced. For example:

   # Incorrect:
   echo "Hello
   # Correct:
   echo "Hello"
   

3. Ensure special characters are escaped if they should be taken literally:

   # Incorrect (the asterisk will expand to file names):
   echo *.txt
   # Correct:
   echo \*.txt
   

4. If the command is long, break it into parts or use a backslash (\) for line continuation.

After fixing, run the command again.

Method 2: Check Zsh configuration files

If the error occurs when opening a new terminal window, the problem is likely in one of Zsh's configuration files (e.g., ~/.zshrc).

1. Look at the full error message. It usually indicates the file and line number:

   /Users/username/.zshrc:15: syntax error near unexpected token `;'
   

2. Open the specified file in an editor. For quick editing, use nano:

   nano ~/.zshrc
   

   If the error is in another file, provide its path.
3. Go to the error line (in nano, press Ctrl + _, then enter the line number).
4. Check the syntax on that line and surrounding lines. Common issues:
   • Missing then after if or elif.
   • Unclosed quotes or brackets.
   • Extra semicolons (;).
   • Using Bash commands instead of Zsh (e.g., echo $BASH_VERSION may be empty in Zsh).
5. Fix the error, save the file (Ctrl + O in nano, then Enter), and exit the editor (Ctrl + X).
6. Apply changes without restarting the terminal:

   source ~/.zshrc
   

   If the error persists, repeat the search in other lines.

Method 3: Temporarily disable configuration files

If you cannot determine which file contains the error, start Zsh without loading configuration files. This helps identify if the problem is related to shell settings.

1. Start a clean Zsh session:

   zsh -f
   

   The -f flag prevents reading configuration files.
2. If the error does not appear in this mode, the issue is in one of the files ~/.zshrc, ~/.zprofile, ~/.zlogin, or ~/.zshenv.
3. To find the problematic file, rename them one by one (e.g., add .backup to the name) and start a new terminal or source the remaining file. Once the error disappears, you've found the culprit.
4. After locating the file, check its syntax as described in Method 2.

Method 4: Reset Zsh configuration

If you cannot find the error manually, the simplest solution is to temporarily reset the configuration to the default.

1. Rename the main configuration file:

   mv ~/.zshrc ~/.zshrc.backup
   

2. Create a new minimal ~/.zshrc:

   echo '# Minimal Zsh configuration' > ~/.zshrc
   

3. Restart the terminal or run source ~/.zshrc. The error should disappear.
4. Now you can gradually migrate settings from the old file (~/.zshrc.backup) to the new one, adding them one by one and checking after each addition whether the error reappears. This will help you identify the problematic line.

Method 5: Check scripts launched from .zshrc

Sometimes ~/.zshrc calls external scripts (e.g., via source or direct execution). The error may be in those scripts, not in ~/.zshrc itself.

1. Open ~/.zshrc and look for lines that run other files:

   source /path/to/script.sh
   

   or

   /path/to/script.sh
   

2. Check the syntax of the referenced scripts. You can use Zsh's syntax-checking mode:

   zsh -n /path/to/script.sh
   

   The -n flag does not execute the script but only checks syntax.
3. Fix errors in the scripts or temporarily comment out their calls in ~/.zshrc to confirm the problem is there.

Prevention

• Always check syntax after editing configuration files. Use source ~/.zshrc or zsh -n ~/.zshrc to catch errors before restarting the terminal.
• Use an editor with syntax highlighting (e.g., VS Code, Sublime Text, or vim with appropriate settings) to spot unclosed quotes or brackets.
• Escape special characters if they should be taken literally. In Zsh, as in Bash, use a backslash (\) or single quotes ('...').
• Do not copy Bash commands into Zsh without checking. Although Zsh in compatibility mode (emulate sh) may handle Bash syntax, it's better to adapt commands for Zsh or explicitly specify the shell (e.g., #!/usr/bin/env bash in scripts).
• Back up configuration files before making major changes. This allows quick rollback in case of an error:

  cp ~/.zshrc ~/.zshrc.bak