← 4.95.2 →
1640 words Slides Slide Issue
Slide Issue: "Permission Denials" Listed as Error

5.1 Common Issues and Solutions

Course: Claude Code - Essentials Section: Troubleshooting Basics Video Length: 2-5 minutes Presenter: Daniel Treasure Studio: Stormwind Studios

Opening Hook

"Claude Code is powerful, but like any tool, things don't always go smoothly on the first try. In the next couple of videos, we're going to walk through the most common issues you'll hit in your first month using Claude Code—and exactly how to fix them. We'll start with four big categories: installation, authentication, permissions, and context limits. Let's dig in."

Key Talking Points

1. Installation Issues (The Basics First)

  • Installation blocks everything else — if it's not working, nothing works
  • Common causes:
  • Wrong operating system (Windows users should use WSL or PowerShell, not CMD)
  • Missing dependencies (Node.js for npm install, Homebrew for macOS)
  • Insufficient permissions (installer needs admin/sudo)
  • Corrupted downloads — always re-download if unsure
  • The fix sequence:
  • Verify your OS and check the official installation docs
  • Install dependencies first (Homebrew, Node.js, etc.)
  • Re-run the installer with proper permissions
  • If still stuck, try the alternative installation method

2. Authentication Issues (The Login Wall)

  • Authentication is the second big blocker
  • Three common scenarios:
  • "Login failed" — credentials expired, account needs reactivation, or network issue
  • "Proxy blocking" — corporate networks sometimes intercept API requests
  • "Subscription expired" — Claude Pro lapsed or account downgraded
  • The fix sequence:
  • Check your network connectivity (test with ping google.com)
  • Log out completely (/logout or delete local tokens)
  • Log back in with your Claude account credentials
  • Verify your plan is still active in Claude dashboard
  • If behind corporate proxy, check with IT — may need to allow api.anthropic.com

3. Permission Errors (Safety That Blocks You)

  • Claude asks for permission on purpose — it's a safety feature
  • Common permission denials:
  • File read/write operations require approval each time (until end of session)
  • Bash commands require approval (and can be permanent per project)
  • File edits are approved per-session by default
  • Why this happens:
  • You're running a command Claude has never asked about before
  • You've set up custom permission rules
  • You're in plan mode (which blocks all modifications)
  • The fix:
  • Read the permission prompt carefully — understand what Claude wants to do
  • Approve it for this session or one-time
  • If you want permanent approval, set it in .claude/settings.json
  • If you're learning, keep the default (ask each time) — it's safer

4. Context Limits (The Silent Killer)

  • This is the hardest issue to spot — it often looks like Claude is just "giving up"
  • What it looks like:
  • Claude stops analyzing your code
  • Responses become short or generic
  • Claude forgets things you mentioned earlier in the conversation
  • "Token limit" or "context full" error messages
  • Why it happens:
  • Long sessions with many code files loaded
  • Repeatedly asking Claude to read large files
  • Many back-and-forth exchanges without clearing context
  • The fix sequence:
  • Use /compact — this condenses the conversation history and frees up space
  • Start a new session — use /resume to pick up where you left off
  • Be selective with file references — use @filename instead of loading entire directories
  • Clear context if stuck — /clear wipes everything (start fresh)
  • Monitor with /usage — some IDEs show token usage; keep an eye on it

Demo Plan

Part 1: Installation Problem Walkthrough (45 seconds)

Goal: Show real installation error and walk through systematic fix

  1. Terminal demo: Show failed installation attempt (pre-recorded)
  2. Display error: "command not found: claude" or "permission denied"

  3. Narrate: "Let's say this is our first try. The installer said 'no.'"

  4. Show fix checklist on screen:

  5. Verify OS with uname -s
  6. Check if Node.js installed: node --version

  7. Demonstrate proper sudo for Homebrew install (don't actually run)

  8. Outcome: Mention how to know it worked

  9. Run claude --version → should show version number

Part 2: Authentication Error (30 seconds)

Goal: Show login flow and what to do when it fails

  1. Terminal: Run claude /login
  2. Show successful login flow (browser opens, user confirms)

  3. Mention credential storage location

  4. If it fails: Show the troubleshooting sequence

  5. Check network: ping api.anthropic.com
  6. Clear cached credentials (explain where they're stored)
  7. Try logging in again

Part 3: Permission Prompt & What to Approve (45 seconds)

Goal: Normalize permission prompts, show they're not errors

  1. Demo session: Ask Claude to edit a file
  2. Show permission prompt appearing
  3. Read it aloud: "Claude wants to modify file X in directory Y"
  4. Approve it

  5. File changes happen

  6. Explain the approval dropdown:

  7. "Approve this time" — only for this command
  8. "Approve for session" — all edits in this session

  9. "Deny" — reject the action (Claude re-asks)

  10. Show how to prevent repeated prompts:

  11. Quick mention of permissions in settings (deep dive in next section)

Part 4: Context Limit Symptom (1 minute)

Goal: Show what context overload looks like

  1. Demo: Long running session with issue
  2. Show conversation that started coherent but becomes rambling
  3. Claude gives generic response when asked specific question

  4. Terminal shows recent prompt but Claude's response is "I don't have context for that"

  5. Apply the fix:

  6. Run /compact → show feedback message
  7. Ask the same question again → Claude responds with full context

  8. Narrate: "That's what context compaction does—it saves tokens, clears the noise, keeps the learning."

  9. Show alternatives:

  10. /resume switching to new session
  11. Starting fresh session with /clear

Code Examples & Commands

Installation Check Commands

# Verify OS type
uname -s

# Check Node.js installation
node --version
npm --version

# Check Homebrew (macOS)
brew --version

# Verify Claude Code installed
claude --version

# Manual reinstall (macOS/Linux with curl)
curl -fsSL https://claude.ai/install.sh | bash

# Manual reinstall (PowerShell on Windows)
irm https://claude.ai/install.ps1 | iex

Authentication Troubleshooting

# Explicitly log in
claude /login

# Check network connectivity to API
ping api.anthropic.com

# Verbose mode to see auth errors
claude --debug

Context & Token Management

# Compact conversation to free tokens
/compact

# View all available commands (includes /usage in some IDEs)
/help

# Start fresh session
/clear

# Resume previous conversation
/resume

Settings for Permission Management

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Edit(/src/**)"
    ],
    "ask": [
      "Bash(git push *)"
    ]
  }
}

Gotchas & Tips

Installation Gotchas

  1. Windows users: Don't use CMD.exe for installation — use PowerShell or WSL2
  2. Homebrew caching: If stuck, run brew update first
  3. Permissions: macOS/Linux users might need sudo for system-level installs
  4. Multiple installations: Check if you already installed via npm globally (causes conflicts)

Authentication Gotchas

  1. Corporate networks: May need proxy configuration or IT allowlisting
  2. Token expiry: Claude Pro subscriptions renew automatically; verify payment method
  3. API keys vs credentials: If using Console API key, that's different from login (mention advanced section)

Permission Gotchas

  1. Not a security issue — prompts are intentional, not bugs
  2. Session-scoped approvals don't persist — next session will re-ask
  3. Plan Mode blocks everything — if you're in plan mode, no edits are allowed (mention earlier section)

Context Gotchas

  1. Not a hard error — Claude doesn't crash; responses just get worse
  2. References to "@" files still count — they load into context, so be selective
  3. /compact isn't magic — it helps but won't save a multi-hour session from degradation
  4. Token count varies by model — Sonnet vs Opus use tokens differently (explain in settings section)

Quick Wins (Mention These)

  • Always try /logout then /login first — fixes 40% of auth issues
  • Approve permissions once per session — you'll learn the pattern
  • Use /compact every 30 minutes in long sessions — preventative medicine
  • Check /help before filing support tickets — many answers are in there

Lead-out

"These four issues—installation, auth, permissions, and context—account for 80% of the problems you'll hit in your first month. The good news? They're all fixable with a few simple steps. In the next video, we're going to introduce you to the /doctor command, which automates a lot of this diagnosis. It's like having a debugger for Claude Code itself. See you in the next one."

Reference URLs

Official Documentation: - Installation Guide: https://code.claude.com/docs/en/overview - Quickstart (includes login): https://code.claude.com/docs/en/quickstart - CLI Reference: https://code.claude.com/docs/en/cli-reference - Permissions System: https://code.claude.com/docs/en/permissions - Settings & Configuration: https://code.claude.com/docs/en/settings

Community Resources: - Release Notes: https://support.claude.com/en/articles/12138966-release-notes - ClaudeLog Best Practices: https://claudelog.com/ - Official Changelog: https://github.com/anthropics/claude-code/releases

Prep Reading

  1. Official Quickstart (5 min read) — Installation and first login flow: https://code.claude.com/docs/en/quickstart
  2. Permissions System Docs (7 min read) — Permission modes and approval rules: https://code.claude.com/docs/en/permissions
  3. Settings & Configuration (8 min read) — How to set permanent permission rules: https://code.claude.com/docs/en/settings
  4. CLI Reference (Skim) — All available commands including /compact, /logout: https://code.claude.com/docs/en/cli-reference

Production Notes

Recording Setup: - Terminal visible with good contrast (dark background, light text) - Show error messages clearly — pause for 2-3 seconds so viewers can read - Use cursor highlighting tool to point at specific UI elements - Pre-record installation failures (they can be slow in real-time)

Script Callouts: - Emphasize that permission prompts are intentional and safe - Normalize troubleshooting as part of the learning curve - Position these issues as solvable (not "Claude Code is broken")

Transitions: - End with clear statement: "Next video shows how to diagnose these problems automatically with /doctor" - Suggest viewers try each fix themselves on a test project