# Claude Code Troubleshooting

> Claude Code: Diagnose Passion8 authentication, Base URL, models, settings, MCP, hooks, permissions, caching, and safe mode.

URL: https://docs.passion8.cc/en/docs/claude-code/troubleshooting
Language: en
Publisher: Passion8

First confirm requests actually reach Passion8, then investigate models, settings, MCP, hooks, and permissions. Do not change many settings at once.

For installation, PATH, login, and OAuth, see [Installation troubleshooting](https://docs.passion8.cc/en/docs/claude-code/install-troubleshooting). For HTTP/API failures, 500/529, limits, large requests, and model errors, see [Error reference](https://docs.passion8.cc/en/docs/claude-code/error-reference). For unloaded settings, hooks, MCP, or memory, see [Configuration debugging](https://docs.passion8.cc/en/docs/claude-code/configuration-debugging).

## Quick diagnosis

| Symptom | Check first | Action |
| --- | --- | --- |
| 401 or unauthorized | ANTHROPIC_AUTH_TOKEN | Check complete, active key and account status; see error reference |
| Connection or path error | ANTHROPIC_BASE_URL | Use https://passion8.cc without /v1 |
| Model not found | Model ID | Select an available Claude model with /model |
| Command not found | Installation and PATH | Check claude --version; check Node/npm only for installations that require them |
| Settings ignored | Wrong file or invalid JSON | claude doctor and /config |
| Hooks do not trigger | Matcher or location | Inspect /hooks |
| MCP disconnected | Scope, trust, OAuth, timeout | /mcp and claude mcp list |
| Repeated permission prompts | Conflicting allow/ask/deny | Inspect /permissions sources |
| Slow first turn | Cache miss | Check model, effort, MCP changes, and upgrades |
| 429, 529, or request too large | Limits, capacity, payload | Reduce concurrency, split tasks, keep model/effort stable |




A common endpoint mistake: Claude Code uses `https://passion8.cc`, not `https://passion8.cc/v1`.




## Minimal connectivity test

Run from a clean directory:

```bash
ANTHROPIC_BASE_URL="https://passion8.cc" \
ANTHROPIC_AUTH_TOKEN="sk-YOUR_PASSION8_API_KEY" \
claude -p "Reply only with ok"
```

If it works, basic key and network connectivity are functioning. Return to the project and inspect .claude, MCP, hooks, and permissions.

## Clean configuration directory

When local configuration may be interfering:

```bash
mkdir -p /tmp/claude-clean
CLAUDE_CONFIG_DIR=/tmp/claude-clean \
ANTHROPIC_BASE_URL="https://passion8.cc" \
ANTHROPIC_AUTH_TOKEN="sk-YOUR_PASSION8_API_KEY" \
claude -p "Test the clean configuration"
```

If this works, common problems in the original configuration include:

- Incorrect user settings.
- Invalid project JSON.
- Failing hook commands.
- An MCP server waiting for authentication or stuck on startup.
- Overly broad permission denials.
- Plugins changing tools or system instructions.

## Safe mode

Safe mode disables most customizations to isolate configuration issues:

```bash
claude --safe-mode
```

It disables:

- CLAUDE.md.
- Skills and plugins.
- Hooks.
- MCP servers.
- Custom commands and agents.
- Output styles and workflows.
- Custom themes, status line, and file suggestions.

Authentication, models, built-in tools, and permissions remain active. Managed policy may still apply.

## Settings do not apply

| Check | Command/action |
| --- | --- |
| Installation/login/config diagnostics | claude doctor |
| Current session | /status |
| Settings UI | /config |
| Loaded context | /context all |
| Hooks | /hooks |
| MCP | /mcp |
| Permission sources | /permissions |
| Output style unchanged | /clear or a new session after changing outputStyle |
| Slow status line | Inspect statusLine.command runtime |
| Missing OTel data | Check telemetry enablement, exporter, endpoint, and headers |

Common locations:

| Content | Location |
| --- | --- |
| User settings | ~/.claude/settings.json |
| Project settings | .claude/settings.json |
| Local settings | .claude/settings.local.json |
| Local/user MCP | ~/.claude.json |
| Project MCP | .mcp.json |
| Project memory | CLAUDE.md or .claude/CLAUDE.md |

## MCP diagnosis

```bash
claude mcp list
claude mcp get <name>
claude mcp login <name>
```

| Symptom | Possible cause |
| --- | --- |
| Pending approval | Project .mcp.json needs workspace trust |
| OAuth failure | Reauthenticate the remote server |
| stdio startup failure | Missing command, environment, or -- separator |
| Output too long | Narrow the query or adjust MAX_MCP_OUTPUT_TOKENS |
| Tools fail on custom gateway | Tool-search setting or unsupported passthrough fields |

## Hook diagnosis

| Symptom | Check |
| --- | --- |
| Never triggers | Relevant settings loaded in /hooks |
| Only some edits trigger | Correct tool-name regex such as Edit|Write |
| Command not found | Absolute path or CLAUDE_PROJECT_DIR |
| Blocking ineffective | permissionDecision inside hookSpecificOutput |
| Slow execution | Narrow the trigger with if |

Empty output is not approval; it continues the normal permission flow.

## Permission diagnosis

| Symptom | Cause |
| --- | --- |
| Still asks after allow | Higher-priority ask or deny matches |
| Allow cannot override broad deny | Deny always wins |
| Compound Bash command prompts | Not every subcommand passed |
| Read path misses | /path is relative to settings source, not filesystem root |
| MCP rule misses | Use mcp__server__tool |

See [Permissions](https://docs.passion8.cc/en/docs/claude-code/permissions).

## Unexpected caching or cost

| Symptom | Explanation |
| --- | --- |
| Slow turn after switching models | Model participates in cache identity |
| Slow after changing effort | Effort can alter cache identity |
| Slow after MCP changes | Tool definitions may change the prompt prefix |
| More cache creation after compact | Conversation replaced by a summary |
| cache_read_input_tokens always zero | Short prompt, changing prefix, or unsupported provider/gateway |

See [Prompt caching](https://docs.passion8.cc/en/docs/claude-code/prompt-caching).

## Official references

- [Debug your configuration](https://code.claude.com/en/docs/en/debug-your-config.md)
- [Troubleshoot installation and login](https://code.claude.com/en/docs/en/troubleshoot-install.md)
- [Troubleshooting](https://code.claude.com/en/docs/en/troubleshooting.md)

## Related pages



- [Installation and login troubleshooting](https://docs.passion8.cc/en/docs/claude-code/install-troubleshooting): Installation, PATH, proxies/TLS, Windows/WSL, Docker, and OAuth.
- [Error reference](https://docs.passion8.cc/en/docs/claude-code/error-reference): Diagnose status codes, authentication, networking, request size, and model configuration.
- [Configuration debugging](https://docs.passion8.cc/en/docs/claude-code/configuration-debugging): Inspect loaded settings, hooks, MCP, skills, permissions, and local data.