Permissions and Security - Troubleshooting

Permission and security issues in Claude Code often block command execution, file access, or writing to certain directories. This troubleshooting guide provides diagnostic commands, probable causes, and concrete solutions to resolve each situation quickly.

Troubleshooting permissions and security in Claude Code is an essential skill for any developer who uses this tool daily. Claude Code v2.1 manages three levels of permissions - read, write, and execute - that interact with the file system, Git, and your organization's security policies.

over 60% of support tickets related to Claude Code involve misconfigured permissions.

What are the most common permission-related symptoms in Claude Code?

Before diving into each issue, here is a summary table of the 12 most common permission errors. This table lets you quickly identify your situation and apply the appropriate solution.

For an overview of permission mechanisms, consult the complete permissions and security guide that details each authorization level.

Key takeaway: identify the exact symptom in the table first before looking for a solution - 80% of issues are resolved in under 2 minutes.

How to diagnose a permission issue in Claude Code?

Diagnosis always starts with information gathering. Run these commands in order to understand the state of your environment.

# Check the Claude Code version
claude --version

# Display the active configuration
claude config list

# Check the working directory permissions
ls -la .

# Test write permissions
touch .claude-test && rm .claude-test

The claude config list command displays all active parameters, including permissions. In practice, 90% of diagnoses are resolved by checking three elements: the installed version, directory permissions, and the active configuration.

Then check the main configuration file. This file is located in .claude/settings.json at your project root or in ~/.claude/settings.json for the global configuration.

{
  "permissions": {
    "allow": ["Read", "Write", "Bash"],
    "deny": ["WebFetch"],
    "allowedTools": ["npm install", "git status"]
  }
}

Specifically, if a command is missing from allowedTools and you are in restrictive mode, Claude Code will ask for manual approval on every execution. For deeper insights into common errors during your first sessions, the guide on common errors in first conversations covers the most frequent cases.

Key takeaway: run claude config list first - this command reveals 90% of configuration issues.

Why does Claude Code refuse to execute certain commands?

Claude Code applies a three-layer security model: global permissions, project permissions, and dynamic approvals. A command can be blocked at any level.

The active permission mode determines the default behavior. Here are the concrete differences between each mode:

the default mode is recommended for 95% of enterprise use cases. Check your active mode with the following command:

claude config get permissions.mode

If you receive the "Tool not allowed" error, it means the specific tool is not in your authorization list. Add it in your project configuration:

{
  "allowedTools": [
    "Bash(npm install)",
    "Bash(npm test)",
    "Bash(git *)"
  ]
}

The Bash(git *) syntax allows all Git commands in a single rule. In practice, this wildcard approach reduces permission-related interruptions by 70%. To understand all available slash commands and their interactions with permissions, consult the guide on common slash command errors.

Key takeaway: the default mode offers the best security/productivity trade-off - only switch to bypassPermissions in a controlled environment.

How to resolve file and directory access errors?

EACCES and Permission denied errors on files account for about 40% of reported issues. Here is how to diagnose and fix them.

Run this command to identify problematic files in your project:

# Find files that are not writable
find . -not -writable -type f -name "*.ts" -o -name "*.json" 2>/dev/null

There are three main causes. First, files cloned from a Git repository may retain restrictive permissions. Second, some editors lock open files. Third, CI/CD tools sometimes modify permissions after a build.

Specifically, after a git clone, systematically run chmod -R u+rw . on the project directory to avoid permission issues. This operation takes less than 2 seconds on a 500 MB project.

The CLAUDE.md memory system requires read and write permissions. If you encounter difficulties with this file, the guide on common CLAUDE.md memory system errors will help you resolve the issue.

Key takeaway: after every git clone, check permissions with ls -la - a preventive chmod -R u+rw . avoids 40% of errors.

How to configure security rules for a team project?

Security in Claude Code is configured at three levels: global (~/.claude/settings.json), project (.claude/settings.json), and session (CLI flags). Project rules take precedence over global rules.

Create a .claude/settings.json file at your project root with this structure:

{
  "permissions": {
    "allow": ["Read", "Edit", "Write", "Glob", "Grep"],
    "deny": ["Bash(rm -rf *)", "Bash(git push --force)"],
    "allowedTools": [
      "Bash(npm test)",
      "Bash(npm run build)",
      "Bash(git add *)",
      "Bash(git commit *)"
    ]
  },
  "security": {
    "ignoredFiles": [".env", ".env.local", "credentials.json"],
    "maxFileSize": "10MB"
  }
}

This configuration allows common development operations while blocking destructive actions. The deny list takes priority over the allow list: if a command appears in both, it will be rejected.

In practice, teams of 5 to 15 developers at SFEIR Institute use this configuration as a base, then adapt it to their specific needs. The permissions and security checklist provides a complete ready-to-use template.

To go further in mastering permissions, the one-day Claude Code training offered by SFEIR guides you through hands-on labs where you configure security policies tailored to your team context. You will learn to define granular rules and audit authorized actions.

Key takeaway: commit the .claude/settings.json file in your repository - the entire team then benefits from the same security rules.

What are the Git-specific permission issues in Claude Code?

Claude Code's Git integration applies additional safeguards. By default, the commands git push --force, git reset --hard, and git clean -f are blocked to protect your history.

Here are the most common Git-related permission errors:

• git push requires manual confirmation on every execution
• git commit --amend is blocked if the previous commit has already been pushed
• git checkout . refuses to execute to protect uncommitted changes
• Pre-commit hooks fail if the file is not executable

Check your Git hooks permissions with this command:

ls -la .git/hooks/

If a hook does not have the executable flag (-rw-r--r-- instead of -rwxr-xr-x), fix it with:

chmod +x .git/hooks/pre-commit
chmod +x .git/hooks/commit-msg

The Git integration troubleshooting guide covers advanced cases such as merge conflicts and rebase errors. If you encounter issues during initial installation, the installation troubleshooting guide addresses initial Git configuration errors.

Key takeaway: Git hooks must have the executable flag (chmod +x) - this is the #1 cause of pre-commit failures in Claude Code.

How to resolve API key and authentication issues?

The Anthropic API key (ANTHROPIC_API_KEY) is the primary authentication mechanism for Claude Code. An invalid, expired, or misconfigured key blocks all functionality.

Verify that your key is correctly set:

# Check if the variable is set
echo $ANTHROPIC_API_KEY | head -c 10

# Test the connection
claude --print "test"

Anthropic API keys start with the sk-ant- prefix. If your key starts differently, it is invalid. API keys have a configurable validity period between 30 and 365 days.

the default Team plan quota is 500,000 tokens per minute. The Enterprise plan goes up to 2,000,000 tokens per minute.

For a quick start with a secure configuration, follow the permissions quickstart guide which includes API key configuration.

Key takeaway: store your API key in ~/.zshrc or a secrets manager - never hardcode it in a versioned file.

Can you customize permission levels per tool?

Claude Code v2.1 allows you to define granular permissions for each tool individually. This feature is particularly useful when you want to allow certain Bash commands while blocking network tools.

The granular configuration uses the ToolName(pattern) syntax:

{
  "allowedTools": [
    "Bash(npm test)",
    "Bash(npm run lint)",
    "Bash(npx jest *)",
    "Edit",
    "Read",
    "Write"
  ],
  "deniedTools": [
    "Bash(curl *)",
    "Bash(wget *)",
    "WebFetch"
  ]
}

This approach allows test and lint commands while prohibiting outbound network requests. In practice, 85% of enterprise projects use this type of fine-grained configuration to comply with their network security policies.

The complete permissions tutorial guides you step by step through setting up these granular rules, with examples adapted to different project types (frontend, backend, monorepo).

If you are looking to deepen these security concepts in a broader framework, the 2-day AI-Augmented Developer training covers secure configuration of AI tools in professional environments, with workshops on team permission policies. For experienced profiles, the one-day AI-Augmented Developer - Advanced training covers advanced security strategies and permission audit automation.

Key takeaway: use the Bash(command) syntax to allow or block individual commands - granularity is the key to effective security.

When should you contact Anthropic support for a permission issue?

Certain issues go beyond the scope of local configuration. Contact Anthropic support in the following cases:

1. Your API key returns a 403 error after regeneration
2. The displayed quota does not match your plan
3. A tool was working then stopped without any configuration change
4. Permission errors appear only on certain machines with the same configuration
5. bypassPermissions mode does not work despite correct configuration

Before contacting support, gather this information:

# Generate a complete diagnostic report
claude --version
node --version
uname -a
claude config list 2>&1
cat .claude/settings.json 2>/dev/null || echo "No project config"

Node.js 22 LTS is the recommended version in 2026 for Claude Code. Versions prior to Node.js 18 are no longer supported and may cause unexpected permission errors.

The general Claude Code troubleshooting guide centralizes diagnostic procedures for all issues, beyond permissions alone. Here is how to prepare your support request:

• Include the complete output of claude --version and node --version
• Attach your .claude/settings.json file (masking API keys)
• Describe the exact steps to reproduce the issue
• Specify whether the issue appeared after an update

Key takeaway: gather the Claude Code version, Node.js version, and your configuration before contacting support - these three elements speed up diagnosis by 50%.

How to audit actions authorized and executed by Claude Code?

Claude Code records each action in a local journal. This journal lets you verify which commands were executed and which permissions were used.

View the recent action journal:

# Display the latest recorded actions
cat ~/.claude/logs/actions.log | tail -20

Each journal entry contains the timestamp, tool type used, command executed, and result (success or failure). In practice, this journal is essential for enterprise compliance audits.

Typical audit metrics for an active project show approximately 150 to 300 actions per day, of which 60% are reads, 25% edits, and 15% Bash commands. These figures help detect anomalies - a sudden spike in Bash commands may indicate a configuration issue.

Specifically, SFEIR recommends establishing a weekly action journal review for sensitive projects. This practice takes 10 minutes and helps detect security policy deviations before they become incidents.

Key takeaway: regularly check ~/.claude/logs/actions.log - proactive permission auditing prevents security incidents.