When It Breaks

Five problems cause almost every Week 1 hold-up. Each one below has the exact fix.

Work through this page before you message the group. Your instructor will ask whether you did.

1. claude: command not found

What you see

claude: command not found

What it means

The install worked, but your terminal does not know about the new command yet. A terminal only checks for available commands when it starts, so one that was already open never learned about it.

The fix, in order

1. Close your terminal completely and open a new one. Not a new tab - close the window. Then try claude --version again. This fixes it about eight times out of ten.

2. Still broken? Restart your laptop. Genuinely. The installer sometimes needs a restart to register.

3. Still broken? Check the install actually succeeded:

   npm list -g @anthropic-ai/claude-code

   If nothing is listed, the install failed silently. Run it again and read the output for the word error:

   npm install -g @anthropic-ai/claude-code

4. If the install itself errors with a permission problem (EACCES on Mac, or "access denied" on Windows), tell your instructor. Do not start running commands with sudo that you found on the internet - that causes worse problems than the one you are fixing.

2. npm run dev says the port is already in use

What you see

Error: listen EADDRINUSE: address already in use :::3000

What it means

Something is already using port 3000. Almost always it is your own site, still running in a terminal window you forgot about.

The fix

First, look for it. Check your other terminal windows and tabs. If you find one running your site, click into it and press Ctrl + C to stop it. Then run npm run dev again.

Cannot find it? Just use a different port:

npm run dev -- -p 3001

Then open http://localhost:3001 instead. Nothing is wrong with using another port.

Want to kill whatever is on 3000?

On Mac:

lsof -ti:3000 | xargs kill

On Windows PowerShell:

Get-Process -Id (Get-NetTCPConnection -LocalPort 3000).OwningProcess | Stop-Process -Force

3. GitHub push fails with an authentication error

What you see

remote: Support for password authentication was removed on August 13, 2021.
fatal: Authentication failed for 'https://github.com/...'

What it means

GitHub stopped accepting your account password from the command line years ago. Your normal password will never work here. You need a personal access token, which is a long password made specifically for this purpose.

The fix

1. Go to github.com/settings/tokens (opens in a new tab)
2. Click Generate new token, then Generate new token (classic)
3. Give it a name, for example codezyn laptop
4. Set Expiration to 90 days - that comfortably covers the course
5. Tick the repo checkbox. That is the only one you need
6. Click Generate token at the bottom
7. Copy the token now. GitHub shows it exactly once. If you lose it, you make a new one
8. Run git push again. When it asks for your username, type your GitHub username. When it asks for your password, paste the token

4. The Vercel deployment fails

What you see

A red Failed on the Vercel dashboard, and a wall of build log.

What it means

Vercel tried to build your site and hit an error. The good news is that a failed deploy cannot break your live site - the previous working version stays up.

The fix

First, find the actual error. Click the failed deployment and scroll the build log to the first red line. Not the last one. The first error is the real cause; everything after it is fallout.

Then check the three common causes, in order:

1. It does not build on your laptop either. Stop npm run dev and run this:

   npm run build

   If that fails locally, the Vercel failure is the same problem. Fix it here, where the feedback is faster.

2. You did not push everything. Run:

   git status

   If it lists files in red, they were never committed. Vercel builds only what is on GitHub, not what is on your laptop.

   git add .
   git commit -m "add missing files"
   git push

3. Still stuck? Copy the first red line from the build log and paste it into Claude Code with:

   My Vercel deployment failed with this error. What does it mean and how do I fix it?

   Paste the error underneath.

5. The page shows an error instead of your homepage

What you see

A dark error screen in the browser, often with a red box and a file name, instead of your site.

What it means

The code has a mistake in it. Usually the change that was just made did not quite work.

The fix

Read which file it names. The error screen tells you the file and often the line number. That is the file to talk to Claude about.

Then paste the whole thing back to Claude:

The page is showing this error instead of my homepage. Here is the full error message:

[paste everything from the error screen]

Please explain what is wrong and fix it.

If Claude's fix does not work, do not just say "still broken." Say:

That did not fix it. The same error is still showing. Stop making changes and explain what you think is causing this, and what else could be causing it.

If it is thoroughly broken and you have a commit, you can go back to your last working version:

git restore .

That throws away every uncommitted change and returns you to your last commit. It is a hard undo, and it is exactly why you commit whenever something works.

Still stuck after all of this

Post in the WhatsApp group with these four things. Anything less and somebody has to ask you for them anyway:

1. What you were trying to do - "I was pushing to GitHub"
2. The exact command you ran - copied, not remembered
3. The full error message - a screenshot of the whole terminal is fine
4. What you already tried - "I restarted the terminal and checked I was in the right folder"

Next → Week 2 - Design