Troubleshooting — When Something Breaks

Breaking things is normal. Here's how to unbreak the common ones. The #1 fix for almost everything: copy the error message, paste it to Claude Code, and say "I got this error, how do I fix it?" This page covers the cases you might hit before Claude Code is set up, plus the greatest hits.

General first-aid#

1. Read the error. It usually says what's wrong in the last line or two.
2. Did you close and reopen the terminal? Many install steps only take effect in a fresh terminal window. Quit Ghostty completely (Cmd + Q) and reopen.
3. Check for typos. Spaces and capitalization matter. cd Downloads ≠ cd downloads. Use Tab to auto-complete and avoid this.
4. Are you in the right folder? Run pwd and ls to confirm. Lots of "file not found" errors are just being in the wrong place.

"command not found"#

You'll usually see this written in full as zsh: command not found: NAME (zsh is just the name of your Mac's terminal language). It means the terminal can't find the program. Usually one of:

• You haven't installed it yet. Install it (e.g. brew install git).
• You need a fresh terminal. Quit and reopen Ghostty.
• It's a typo. Check spelling.

brew: command not found specifically#

Homebrew installed but isn't on your PATH. Run these (Apple Silicon Macs):

echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> ~/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Then quit and reopen Ghostty and try brew --version again. (On older Intel Macs the path is /usr/local/bin/brew instead.)

"permission denied" / "operation not permitted" / install fails on a corporate laptop#

If you see permission denied or operation not permitted, it's almost always your company's security software, not you doing something wrong.

• Don't try to force it with sudo — that causes worse problems.
• Do go back to Module 01 and loop in IT with the specific tool that's blocked.
• Check whether your company's self-service app catalog already offers the tool (VS Code and Git often are).
• If it's a file you can't touch, you may just be outside your home folder — cd ~ and work there.

"No such file or directory"#

The terminal looked where you pointed it and found nothing there. Almost always a location or spelling problem, not a broken setup:

• Wrong folder. Run pwd to see where you are and ls to see what's actually here. Lots of these errors are just being in the wrong place.
• Typo or wrong case. report.PDF ≠ report.pdf. Use Tab to auto-complete names instead of typing them.
• A name with spaces. cd My Reports fails; use quotes — cd "My Reports".

Claude Code won't install (npm install -g errors)#

• Permission errors with npm: There's an official native installer that avoids npm entirely. Ask Claude (on claude.ai) or check the Claude Code docs for the current "native installer" command. Avoid sudo npm.
• npm: command not found: Node didn't install or you need a fresh terminal. Re-run brew install node, then reopen Ghostty.

Ghostty / VS Code won't open ("unidentified developer")#

macOS is being cautious about apps not from the App Store.

• Right-click the app in Applications → Open → Open.
• If a corporate policy fully blocks it, that's an IT request (Module 01).

code . doesn't open VS Code#

The code command isn't installed yet. Open VS Code, press Cmd + Shift + P, type Shell Command: Install 'code' command in PATH, press Enter. Then reopen the terminal. (See Module 04.)

uv / Python problems#

• uv: command not found: Run brew install uv, then reopen the terminal.
• A uv run fails about a missing package: The project needs an ingredient. Usually uv add THE-PACKAGE-NAME fixes it — but easier: tell Claude Code "this failed with a missing package error" and let it run the right uv add.

Claude Code did something I didn't want#

• It changed/deleted files: If you committed to Git first (you should), run git restore . to rewind. If you worked on copies, just delete the copies.
• It's going down the wrong path: Just tell it. "Stop — that's not what I meant. I actually want..." You can always redirect mid-task.
• It's stuck or looping: Press Ctrl + C to interrupt, then give clearer instructions or break the task into smaller steps.

A command is "stuck" (nothing happening)#

• It might just be working (downloads, big jobs). Wait a minute.
• If it's truly frozen, press Ctrl + C to cancel and try again.
• If you typed a command and got a > prompt you didn't expect, you probably have an unclosed quote. Press Ctrl + C and retype carefully.

I'm overwhelmed / lost my place#

• Take a break. None of this expires.
• Go back to the last module you fully finished and redo its hands-on section — repetition builds the comfort.
• Ask Claude Code to be your tutor: "I'm a beginner and I'm confused about [X]. Explain it simply and quiz me."

The escape hatch for everything#

When in doubt, the most powerful debugging tool you have is a sentence:

"I was trying to [goal]. I ran [command]. I expected [X] but got [this error/ behavior]. What do I do?"

Paste that into Claude Code (once it's installed) or claude.ai. It's right almost every time.