TROUBLESHOOTING

Troubleshooting

Solutions to common installation and usage problems.

"command not found" after install

The tool installed but your shell can't find it. Your PATH needs to include the npm global bin directory.

$ source ~/.zshrc # macOS: reload shell config

$ source ~/.bashrc # Linux/WSL: reload shell config

$ npm list -g --depth=0 # check installed packages

If reloading doesn't work, close your terminal entirely and open a new one.

Node.js version too old

These CLI tools require Node.js 20 or newer.

$ node --version # check current version

$ nvm install --lts # install latest LTS via nvm

If you don't have nvm, install it from github.com/nvm-sh/nvm or use your OS package manager to update Node.js directly.

npm permission errors (EACCES)

npm is trying to install to a directory you don't own. Fix by setting a user-level global prefix.

$ mkdir -p ~/.npm-global

$ npm config set prefix '~/.npm-global'

$ echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc

$ source ~/.zshrc

On Linux, replace ~/.zshrc with ~/.bashrc. Never use sudo npm install.

API key not working

Authentication failed or the key isn't being read.

$ echo $ANTHROPIC_API_KEY # check key is set

$ echo $ANTHROPIC_API_KEY | cat -A # check for invisible chars

Claude Code can also authenticate via claude login (browser-based OAuth). If that's stuck, try claude logout first.

CLAUDE.md not being read

Your context file exists but Claude Code doesn't seem to follow its instructions.

File must be named exactly CLAUDE.md (case-sensitive on macOS and Linux).

Must be in the directory where you run claude, or in a parent directory.

Run /config inside Claude Code to see which files loaded.

Apply the deletion test: generic instructions ("be accurate") won't change behavior. Specific ones ("use 'council member' not 'councilman'") will.

Slow responses or token limit exceeded

Long conversations build up context that slows responses and can hit limits.

$ /compact # compress conversation history

$ /clear # start fresh

$ /cost # check token usage

For large tasks, break work into smaller requests and start new sessions between them.

Windows-specific issues

Line ending problems

$ git config --global core.autocrlf input

Script execution blocked

PS> Set-ExecutionPolicy RemoteSigned -Scope CurrentUser

WSL vs PowerShell

These are separate environments with separate installs. Tools installed in WSL won't appear in PowerShell and vice versa. Pick one and stay consistent.

Gemini CLI rate limiting

The free tier allows 1,000 requests per day. If you hit limits, use a smaller model:

$ gemini -m gemini-2.0-flash-lite "your prompt"

Flash Lite uses fewer resources per request. For pipelines, add 2-second pauses between API calls.

Still stuck?

Run /doctor inside Claude Code for an automated health check. For Gemini, try gemini --version to confirm it's installed.

Post in the course discussion forums with your OS, the command you ran, and the full error message. Screenshots help.