From 5f3f21a8c5b41e889f1dfd56fdc8beab2e7481e9 Mon Sep 17 00:00:00 2001 From: Vadym Samoilenko Date: Fri, 17 Apr 2026 12:44:18 +0100 Subject: [PATCH] vault backup: 2026-04-17 12:44:18 --- .../Barclays Banner Builder.md | 5 + 99 Daily/2026-04-17.md | 3 + wiki/claude-code/error-reference.md | 218 ++++++++++++++++++ 3 files changed, 226 insertions(+) create mode 100644 wiki/claude-code/error-reference.md diff --git a/01 Projects/Barclays-banner-builder/Barclays Banner Builder.md b/01 Projects/Barclays-banner-builder/Barclays Banner Builder.md index 91dc3c7..09c5038 100644 --- a/01 Projects/Barclays-banner-builder/Barclays Banner Builder.md +++ b/01 Projects/Barclays-banner-builder/Barclays Banner Builder.md @@ -23,6 +23,10 @@ created: 2026-04-17 - **Local path:** `/Volumes/SSD/Projects/Oliver/Barclays-banner-builder` ## Sessions +### 2026-04-17 – How to deploy the app on +**Asked:** How to deploy the app on Ubuntu server with Docker, idempotent deployment script, and fix Apache routing issues? +**Done:** Created idempotent deploy script with Docker build, database initialization, migrations, and fixed Apache VirtualHost configuration by reordering Include directives. + ### 2026-04-17 – Create an idempotent deployment script for **Asked:** Create an idempotent deployment script for Ubuntu server with Docker containers, database initialization, and migrations. **Done:** Diagnosed Apache reverse proxy configuration issue where VirtualHost Alias directives were intercepting requests before ProxyPass rules. @@ -123,6 +127,7 @@ created: 2026-04-17 ## Change Log | Date | Requested | Changed | Files | |------|-----------|---------|-------| +| 2026-04-17 | Deployment setup | deploy.sh creation, Apache VirtualHost reordering, Docker build cache management | deploy.sh, /etc/apache2/sites-available/optical-dev.oliver.solutions.conf | | 2026-04-17 | Deployment script & Apache config | Docker build caching, idempotent database init, Alembic migrations, Apache ProxyPass setup | deploy.sh, optical-dev.oliver.solutions.conf | | 2026-04-17 | Deployment script & Apache config | Docker build caching, database migrations, Apache proxy setup | deploy.sh, optical-dev.oliver.solutions.conf | | 2026-04-17 | Deployment script | Docker build caching, database init, migrations, frontend cleanup | deploy.sh, main.py | diff --git a/99 Daily/2026-04-17.md b/99 Daily/2026-04-17.md index dc3310d..7321fcb 100644 --- a/99 Daily/2026-04-17.md +++ b/99 Daily/2026-04-17.md @@ -134,3 +134,6 @@ tags: [daily] - 12:43 (<1min) | `memory-compiler` - **Asked:** Compile a new article about plugin marketplaces into the wiki knowledge base. - **Done:** Created structured wiki article at `wiki/claude-code/plugin-marketplaces.md` with LSP tables, MCP bundles, and scope system documentation, then updated master index. +- 12:43 (<1min) | `Barclays-banner-builder` + - **Asked:** How to deploy the app on Ubuntu server with Docker, idempotent deployment script, and fix Apache routing issues? + - **Done:** Created idempotent deploy script with Docker build, database initialization, migrations, and fixed Apache VirtualHost configuration by reordering Include directives. diff --git a/wiki/claude-code/error-reference.md b/wiki/claude-code/error-reference.md new file mode 100644 index 0000000..3c92015 --- /dev/null +++ b/wiki/claude-code/error-reference.md @@ -0,0 +1,218 @@ +--- +title: "Claude Code Error Reference" +aliases: [claude-code-errors, runtime-errors, api-errors] +tags: [claude-code, errors, troubleshooting, api, debugging] +sources: [raw/Error reference.md] +created: 2026-04-17 +updated: 2026-04-17 +--- + +# Claude Code Error Reference + +Runtime errors Claude Code displays during operation. All three surfaces (CLI, Desktop app, Web) share the same error set since they wrap the same CLI. Errors shown here mean retries (up to 10, exponential backoff) have already been exhausted. + +## Retry Behavior + +Claude Code retries automatically before surfacing any error. Spinner shows `Retrying in Ns · attempt x/y`. + +| Env Var | Default | Effect | +|---|---|---| +| `CLAUDE_CODE_MAX_RETRIES` | 10 | Retry attempts | +| `API_TIMEOUT_MS` | 600000 (10 min) | Per-request timeout in ms | + +--- + +## Server Errors + +Originate in Anthropic infrastructure — not your account or request. + +### 500 Internal Server Error +- **Cause:** Unexpected API failure, unrelated to your prompt +- **Fix:** Check [status.claude.com](https://status.claude.com), wait a minute, type `try again`. Run `/feedback` if it persists. + +### 529 Overloaded +``` +API Error: Repeated 529 Overloaded errors +``` +- **Cause:** API at capacity across all users; does NOT count against your quota +- **Fix:** Wait a few minutes; run `/model` to switch models (capacity tracked per model) + +### Request Timed Out +- **Cause:** High load or very large response; default timeout is 10 min +- **Fix:** Retry; break large tasks into smaller prompts; raise `API_TIMEOUT_MS` for slow networks + +### Auto Mode Safety Classifier Unavailable +``` + is temporarily unavailable, so auto mode cannot determine the safety of +``` +- **Cause:** Classifier model overloaded; reads/searches/edits in working directory still work +- **Fix:** Retry after a few seconds; transient, no settings change needed + +--- + +## Usage Limits + +Tied to your account/plan quota, distinct from server errors. + +### Session / Weekly / Model Limit +``` +You've hit your session limit · resets 3:45pm +You've hit your weekly limit · resets Mon 12:00am +``` +- **Fix:** Wait for reset; run `/usage` to check limits; `/extra-usage` to buy more on Pro/Max; monitor with `rate_limits` in [[wiki/claude-code/overview|statusline]] or Desktop usage ring + +### 429 Rate Limit +``` +API Error: Request rejected (429) +``` +- **Cause:** Rate limit on your API key, Bedrock project, or Vertex AI project +- **Fix:** Run `/status` — a stale `ANTHROPIC_API_KEY` may be routing to a low-tier key; lower `CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`; reduce parallel subagents + +### Credit Balance Too Low +- **Fix:** Add credits at platform.claude.com/settings/billing; enable auto-reload; set per-workspace spend caps + +--- + +## Authentication Errors + +Run `/status` to see which credential is active. + +| Error | Cause | Fix | +|---|---|---| +| `Not logged in` | No valid credential | `/login` or set `ANTHROPIC_API_KEY` | +| `Invalid API key` | Key rejected | Check Console for revocation; run `env \| grep ANTHROPIC` to find stale `.env` keys | +| `Organization has been disabled` | Disabled org key overrides subscription | Unset `ANTHROPIC_API_KEY`, relaunch | +| `OAuth token revoked/expired` | Session token invalid | `/logout` then `/login` | +| `OAuth scope: user:profile` | Token predates new scope | `/login` to mint fresh token | + +**Auth precedence:** `ANTHROPIC_API_KEY` env var overrides `/login` subscription, even in non-interactive mode (`-p`). + +--- + +## Network Errors + +Almost always local: VPN, proxy, or firewall — not Anthropic infrastructure. + +### Unable to Connect +``` +Unable to connect to API (ECONNREFUSED / ECONNRESET / ETIMEDOUT) +``` +- **Diagnose:** `curl -I https://api.anthropic.com` from same shell +- **Fix:** Set `HTTPS_PROXY`; set `ANTHROPIC_BASE_URL` for LLM gateways; allow `api.anthropic.com` in firewall +- **WSL:** Check `/etc/resolv.conf` for broken nameserver +- **macOS:** Stale VPN tunnel interfaces (`ifconfig` → remove utun); Docker Desktop can intercept traffic + +### SSL Certificate Errors +``` +SSL certificate verification failed +Self-signed certificate detected +``` +- **Cause:** Corporate proxy doing TLS inspection; Node.js doesn't trust its cert +- **Fix:** `NODE_EXTRA_CA_CERTS=/path/to/ca-bundle.pem` — do NOT use `NODE_TLS_REJECT_UNAUTHORIZED=0` + +--- + +## Request Errors + +API received the request but rejected its content. + +### Context Window Full +``` +Prompt is too long +``` +- **Fix:** `/compact` to summarize; `/clear` to start fresh; `/context` to inspect usage; disable unused MCP servers with `/mcp disable `; trim `CLAUDE.md` files +- **Note:** Auto-compact is on by default; re-enable if `DISABLE_AUTO_COMPACT` was set +- **Subagents:** Inherit all parent MCP tool definitions — disable unused MCP before spawning + +### Compaction Failed +``` +Error during compaction: Conversation too long +``` +- **Fix:** Press Esc twice → step back several turns → run `/compact` again; or `/clear` + `/resume` + +### Request Too Large (30 MB HTTP limit) +- **Fix:** Press Esc twice; reference large files by path instead of pasting + +### Image Too Large +- **Fix:** Press Esc twice; max 8000px longest edge (single image), 2000px when many images in context; take tighter screenshots + +### PDF Errors +- Too large (>100 pages / 32 MB): use Read tool with page range or `pdftotext` +- Password protected: remove protection first +- Invalid: re-export from source + +### Extra Inputs Not Permitted (400) +``` +API Error: 400 ... Extra inputs are not permitted ... context_management +``` +- **Cause:** LLM gateway strips `anthropic-beta` header but forwards body with beta-only fields +- **Fix:** Configure gateway to forward `anthropic-beta`; or set `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS=1` + +### Model Not Found / No Access +- **Fix:** Run `/model` to pick from available models; use aliases (`sonnet`, `opus`) instead of versioned IDs to avoid staleness + +### Opus Not Available on Pro Plan +- **Fix:** `/model` to select an included model; if recently upgraded, `/logout` then `/login` to refresh token + +### `thinking.type.enabled` Not Supported +- **Cause:** Claude Code version < v2.1.111 on Opus 4.7 +- **Fix:** `claude update` to v2.1.111+; or switch to Opus 4.6 / Sonnet + +### Thinking Budget Exceeds Output Limit +``` +max_tokens must be greater than thinking.budget_tokens +``` +- **Cause:** Common on Bedrock/Vertex when `MAX_THINKING_TOKENS` > provider output limit +- **Fix:** Lower `MAX_THINKING_TOKENS` or raise `CLAUDE_CODE_MAX_OUTPUT_TOKENS` + +### Tool Use / Thinking Block Mismatch (400) +``` +API Error: 400 due to tool use concurrency issues +``` +- **Cause:** Conversation history corrupted (interrupted tool call or mid-stream edit) +- **Fix:** `/rewind` or Esc × 2 to step back to a clean checkpoint + +--- + +## Response Quality Seems Off (No Error) + +Claude Code never silently downgrades models. Check: + +1. **`/model`** — confirm expected model; `ANTHROPIC_MODEL` env var may override +2. **`/effort`** — check reasoning level; raise for hard tasks (`ultrathink`) +3. **`/context`** — check window fill level; `/compact` or `/clear` if near capacity +4. **`/doctor`** — flags oversized `CLAUDE.md` files and subagent definitions +5. **Rewind, don't correct** — press Esc × 2 or `/rewind` before the bad turn; replying keeps the wrong answer in context + +--- + +## Reporting + +- `/feedback` — sends transcript + description to Anthropic (unavailable on Bedrock/Vertex/Foundry) +- `/doctor` — local config check +- [status.claude.com](https://status.claude.com) — active incidents +- GitHub issues: anthropics/claude-code + +--- + +## Key Takeaways + +- **Retries are automatic** — when you see an error, 10 retries with backoff have already run +- **529 ≠ your quota** — overloaded errors don't count against usage limits +- **`ANTHROPIC_API_KEY` wins** — an env var key always overrides `/login` subscription, including disabled-org keys hiding in `.env` files +- **Gateway proxy issues** surface as `Extra inputs not permitted` when `anthropic-beta` header is stripped +- **Context errors:** `/compact` → Esc×2 to step back → `/compact` again → `/clear` as last resort +- **Image errors persist** until you Esc×2 past the turn that added the image +- **Quality issues:** check `/model`, `/effort`, `/context` before assuming model regression; prefer `/rewind` over in-thread correction + +## Related + +- [[wiki/claude-code/overview|Claude Code Overview]] — full product capabilities, all surfaces +- [[wiki/claude-code/mcp-integration|MCP Integration]] — MCP server errors and `/mcp disable` usage +- [[wiki/claude-code/custom-subagents|Custom Subagents]] — context inheritance issues when spawning subagents + +--- + +## Sources + +- `raw/Error reference.md` — scraped from code.claude.com/docs/en/errors