open/claude-code-first-project
1
0
Fork 0
Code Activity Actions
claude-code-first-project/troubleshooting.md
Kjell Tore Guttormsen ec708ba943 Initial commit: todo app guide with 5 prompts and examples 
Complete companion repo for "Your First Hour with Claude Code" article.
Includes step-by-step prompts, example output, troubleshooting, and cost guide.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
2026-03-15 16:04:07 +01:00

2.5 KiB
Raw Permalink Blame History

Troubleshooting

Common problems during your first Claude Code session and how to fix them.

Installation Issues

"command not found" after installing

Close your terminal completely and open a new one. The installer adds Claude Code to your PATH, but the current session does not pick it up.

If that does not work:

  1. Check if the binary exists: ls ~/.claude/local/bin/claude
  2. Add it to your PATH manually: export PATH="$HOME/.claude/local/bin:$PATH"
  3. Add that line to your ~/.zshrc (Mac) or ~/.bashrc (Linux) to make it permanent

Windows: curl command fails

Use the Windows package manager instead:

winget install Anthropic.ClaudeCode

Or download the desktop app to skip the terminal entirely.

"Permission denied" on Mac/Linux

Run with explicit permissions:

curl -fsSL https://claude.ai/install.sh | bash

If that fails, try:

curl -fsSL https://claude.ai/install.sh -o install.sh
chmod +x install.sh
./install.sh

Authentication Issues

Browser does not open for sign-in

  1. Copy the URL that Claude Code prints in the terminal
  2. Paste it into your browser manually
  3. Complete the sign-in and return to the terminal

"Not authenticated" error

Run claude auth login and complete the browser sign-in again.

During Your Session

Claude Code seems stuck or takes a long time

It is thinking. Complex tasks can take 30-60 seconds. If it has been more than two minutes with no output, press Ctrl+C to cancel and try again with a simpler prompt.

The generated app does not work

Tell Claude Code what is wrong. Be specific:

  • "The add button does nothing when I click it"
  • "Tasks are not saved when I refresh the page"
  • "The dark mode background is white instead of dark"

Claude Code will read the file, find the bug, and fix it.

Claude Code asks permission for everything

This is normal and good. It asks before creating files and running commands. Type y to approve.

If you want fewer prompts, press Shift+Tab to switch to a faster permission mode. But for your first session, keep the default mode so you can see exactly what it does.

"Context window limit" warning

Your session is getting long. Start a new one:

  1. Type /clear to reset the conversation
  2. Or exit with Ctrl+C and run claude again

Your files are saved on disk. A new session reads them fresh.

Still Stuck?

Describe your problem to Claude Code itself. Paste the error message and ask what went wrong. It usually knows.