module 01 setup

Troubleshooting

System Text-to-Speech Ready
Slide: 0:00 / 0:00
Slide 1 of 0Interactive Deck

Full Lesson Reference

This lesson covers common errors you might encounter when installing or starting Claude Code. Once Claude is running, it will troubleshoot other system issues for you.

The Troubleshooting Loop: Screenshot and Ask

If you get stuck during installation:

  1. Take a screenshot of the error in your terminal.
  2. Paste the screenshot into claude.ai or chatgpt.com in your web browser.
  3. Type: "I am trying to install Claude Code on [Mac/Windows] and got this error. Walk me through fixing it step-by-step."
  4. Follow the instructions, screenshot the next error if one appears, and repeat.

Once Claude Code is successfully running, you can paste any command line errors directly into your active Claude session and ask it to diagnose and patch the issue.

Common Installation & Startup Errors

"claude: command not found"

  • Solution: Close your terminal app completely and reopen it. Your system path needs to refresh to recognize the new executable.
  • Windows Git Bash: If PowerShell runs Claude but Git Bash throws this error, open PowerShell, start a claude session, and tell it: "Set up my Git Bash PATH so I can run claude from Git Bash."

"Permission denied" or "EACCES"

  • Mac: Re-run the installation command with sudo in front: 
    terminal
    sudo curl -fsSL https://claude.ai/install.sh | bash
    (Enter your macOS administrator password when prompted).
  • Windows: Right-click PowerShell or Git Bash and select Run as administrator, then re-run the installation command.

"Running scripts is disabled on this system" (Windows)

Windows security prevents running unsigned scripts by default. To allow the installer:

  1. Open PowerShell as Administrator.
  2. Run this command: 
    terminal
    Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
  3. Re-run the installer command.

"Claude Code requires git-bash" (Windows)

If Claude cannot find Git Bash automatically, set an environment variable:

  1. Confirm Git Bash is installed (usually at C:\Program Files\Git\bin\bash.exe).
  2. Search for "Environment Variables" in the Start menu and click Edit the system environment variables.
  3. Under User variables, click New... and enter:
    • Variable name: CLAUDE_CODE_GIT_BASH_PATH
    • Variable value: C:\Program Files\Git\bin\bash.exe
  4. Click OK, restart your terminal, and try running claude again.

Anthropic Sign-in Won't Complete

If the authentication link in your browser does not log you in:

  • Copy the full URL from the terminal and paste it manually into the browser window where you are logged into your Anthropic account.
  • If using multiple browser profiles, ensure it opens in your active profile.

Exercises

  1. Bookmark this page for quick reference if you ever hit an environment path error.
  2. Windows users: verify whether PowerShell and Git Bash can both execute claude --version. If Git Bash throws an error, set up the CLAUDE_CODE_GIT_BASH_PATH variable or run the path fix through PowerShell.
  3. Keep this troubleshooting workflow in mind: when faced with any console error, screenshot and ask Claude to solve it.