Appendix D: Known Issues + FAQ

Status: drafted · Time: 10 min · Audience: everyone Outcome: Find the known fix for a problem you have hit, or the contribution path for a problem you have just solved.

What this is. A living ledger of problems builders have hit and the fixes that worked. Organised by stack layer so a reader who knows roughly where their problem lives can find the relevant entries quickly. Entries are promoted here from #ai-help threads and from per-belt chapter failure-mode sections; the chapters remain the canonical reference for each pattern.

How to use this appendix

If you have a problem:

1. Identify which stack layer it lives in (sections below).
2. Read the entries in that layer.
3. If your problem matches, follow the documented fix.
4. If the fix does not work, follow the layer’s escalation path.

If you solved a problem and want to contribute:

1. Identify the layer your fix belongs in.
2. Add an entry using the format at the bottom of this page.
3. Open a PR against this appendix.
4. The cohort lead reviews monthly; entries merge in batches.

---

Layer 0 — Foundation (environment, access, setup)

Problems with laptop setup, the setup script, the Zscaler cert, the LiteLLM gateway, or your shell environment.

Escalation path: #ai-help.

D.1 — Manager OOO blocks MyAccess approval (status: fixed)

Symptom. You submitted the MyAccess request for “Claude AI” and your manager is on leave; the request sits in Pending.

Diagnosis. MyAccess routes to your reporting manager by default. With them out, nothing moves.

Fix. Post in #ai-help with @techit tagged and a one-line “manager OOO, requesting bypass.” Admins bulk-approve in batches; expect about an hour business-time. After approval there is still a ~30–40 minute Azure AD sync window before Claude.ai shows your seat.

References. W.5 failure mode #1.

D.2 — “Free Plan” showing on claude.ai after MyAccess approval (status: fixed)

Symptom. MyAccess says approved, but claude.ai signs you in and shows you on the Free Plan.

Diagnosis. Azure AD sync between MyAccess approval and Anthropic’s SSO IdP runs on a cadence; you are inside the sync window.

Fix. Wait 30–40 minutes after approval and retry. If you are still on Free Plan past 60 minutes, post in #ai-help.

References. W.5 failure mode #2.

D.3 — 403 PERMISSION_DENIED referencing aiplatform.googleapis.com (status: fixed)

Symptom. Running claude errors out with 403 PERMISSION_DENIED mentioning aiplatform.googleapis.com or pod-velocity-claude-code.

Diagnosis. Stale Vertex environment variables in your shell rc, left over from the pre-March-2026 Vertex-era setup. The new setup script auto-purges these from new shells, but it cannot purge what your current shell has already loaded.

Fix. Open ~/.bashrc and ~/.zshrc. Remove these lines if present:

export ANTHROPIC_VERTEX_PROJECT_ID='pod-velocity-claude-code'
export CLAUDE_CODE_USE_VERTEX=1
export CLOUD_ML_REGION='global'

Re-run the setup script: curl -fsSL https://get-claude.dev.razorpay.in/setup.sh | bash. Then close the terminal window and open a new one. The new shell loads cleanly.

References. W.4, W.5 failure mode #3.

D.4 — 401 authentication_error after a laptop restart (status: fixed)

Symptom. Claude Code was working yesterday. After a laptop restart, every prompt errors with 401 authentication_error.

Diagnosis. Your LiteLLM key rotated or its OAuth-derived expiry passed.

Fix. Re-run the setup script. It re-mints a fresh key and writes it into ~/.claude/settings.json.

References. W.5 failure mode #4.

D.5 — Opus 4.6 or 4.7 reports exceeded budget (status: workaround)

Symptom. Claude Code errors with exceeded budget for model=claude-opus-4-6 or claude-opus-4-7, while the same error or the gateway shows that route in your enabled-model list.

Diagnosis. The request reached an enabled frontier model whose LiteLLM per-model cap is exhausted. Exceeded budget describes quota; it does not prove the route retired. Model availability can change, so use the current enabled-model list rather than inferring status from the version number.

Fix. Check the LiteLLM usage view, then move routine work to a lower-cost route that your key already enables, such as Sonnet, an approved GPT route, or an approved open-weight model. Do not change the Opus default to 4.8 solely because 4.6 or 4.7 reports a budget error; another frontier route can have its own cap. If the error says your total user budget is exhausted, follow D.6. If the route is absent from the enabled list or returns key_model_access_denied, follow D.13 instead. For an approved business blocker, post in #ai-help with the blocked work and manager approval visible.

References. W.5 failure mode #6, D.6 — model-wise or total usage limit, D.13 — model access, #ai-help current enabled-route and model-cap response 2026-07-17.

D.6 — Hit a model-wise or LiteLLM usage limit (status: workaround)

Symptom. Claude Code starts refusing prompts with ExceededBudget; Server is temporarily limiting requests (not your usage limit) followed by exceeded budget for model=...; a model that worked yesterday is now restricted; a visible spend limit drops; or #ai-help says quota extensions are not being granted by default. The claude.ai usage page may show a different remaining balance.

Diagnosis. Claude Code usage is governed by the LiteLLM gateway, not the separate claude.ai usage page. The CLI path has a centrally managed total cap across enabled gateway models, including open-weight routes such as Kimi, Qwen, and DeepSeek. Frontier models can have per-model caps; open-weight models draw from the overall budget without per-model caps today. Support can change caps based on platform policy or overall spend, so do not treat any dollar amount you saw last week as a durable entitlement.

Fix. Treat the LiteLLM error as authoritative, even when the Claude prefix says not your usage limit. Read the trailing phrase: exceeded budget for model=claude-sonnet-4-6 means that model cap is exhausted; ExceededBudget: User=... over budget means the total LiteLLM cap is exhausted.

To check which limit you hit:

1. Open the LiteLLM Usage view and sign in.
2. Set the date filter to Month to date.
3. Find Top Public Model Names and read the spend for the model named in your error. The total-spend card can still show headroom after one frontier model has exhausted its own cap.
4. If only that model is capped, move routine work to Sonnet, an approved GPT route, or an enabled open-weight model; quota bumps are not automatic. If the error shows total-budget exhaustion, another gateway model or open-weight route will not bypass it.

Do not request Claude Team as a quota workaround: seats are limited, separately provisioned, and may be exhausted. For an approved business blocker, get your org leader’s approval and work with IT on a quota extension; include the blocked work and approval in your support request.

References. W.5 failure mode #7, #product-function-announcements 2026-06-30 model-wise limits post, #ai-help per-model cost question 2026-06-16, #ai-help per-model usage question 2026-07-03, #ai-help model-wise breakdown question 2026-07-20, #ai-help Usage-tab walkthrough 2026-07-20, #ai-help OSS total-cap clarification 2026-07-03, #ai-help open-weight cap clarification 2026-07-06, #ai-help misleading rate-limit wording thread 2026-07-07, #ai-help Team-seat exhaustion announcement 2026-07-17, #ai-help Team-seat and quota route 2026-08-25.

D.7 — Usage not visible in the LiteLLM dashboard (status: fixed)

Symptom. Claude Code is working and you’re definitely using it, but the LiteLLM dashboard shows no traffic for your user.

Diagnosis. Shell-level environment variables ANTHROPIC_BASE_URL or ANTHROPIC_API_KEY are overriding what ~/.claude/settings.json sets. Claude Code is reaching Anthropic directly with the wrong key, bypassing the gateway.

Fix.

unset ANTHROPIC_BASE_URL ANTHROPIC_API_KEY

Then grep your ~/.bashrc and ~/.zshrc for those same variables and remove any persisted definitions. Close the terminal and open a new one.

References. W.5 failure mode #8, W.4.

D.8 — command not found: claude after install (status: fixed)

Symptom. Setup script ran without errors, but claude --version returns command not found.

Diagnosis. Either your shell PATH did not pick up the new install, or you ran the setup script in one terminal and tried to use claude in another that was opened before the script finished.

Fix. Close all terminal windows opened before the setup script ran. Open a new one. If claude --version still fails, re-run the setup script in the fresh terminal.

References. W.5, W.4.

D.9 — Zscaler certificate errors during installs or Claude startup (status: fixed)

Symptom. Package installs fail with certificate, SSL, or “self-signed certificate in certificate chain” wording; or Claude Code / Claude Desktop fails with UNKNOWN_CERTIFICATE_VERIFICATION_ERROR, ERR_SOCKET_CLOSED, a blank startup screen, or Anthropic TLS/preconnect errors.

Diagnosis. Zscaler is intercepting the HTTPS connection, but the current terminal/app session does not trust the Zscaler root certificate or has a stale Zscaler connection. This is a certificate-trust problem, not a reason to disable SSL checks.

Fix. Use this order:

1. Re-run the setup script; it installs the Zscaler trust chain:

   curl -fsSL https://get-claude.dev.razorpay.in/setup.sh | bash

2. Close old terminals, open a fresh terminal, and retry claude or the install command.

3. If Claude still fails with certificate or TLS wording, open Zscaler Client Connector, re-authenticate / reconnect it, then restart Claude Desktop or the terminal session.

4. If it still fails, post in #ai-help with the exact failing command, the redacted error text, your OS, and whether you were on office or home network. Do not bypass certificate checks.

References. W.5, #ai-help certificate thread 2026-07-03, #ai-help Claude Desktop/TLS thread 2026-07-03.

D.10 — claude native binary not installed after install (status: fixed)

Symptom. Running claude or claude /login prints Error: claude native binary not installed, followed by wording about postinstall, --ignore-scripts, or --omit=optional.

Diagnosis. The JavaScript wrapper is on PATH, but the platform-native Claude Code binary was not downloaded or its postinstall step did not run. This is different from command not found: claude: your shell can find the wrapper, but the wrapper cannot find the native binary it needs to start.

Fix. Re-run the Razorpay setup script from a fresh terminal, then close every old terminal window and open a new one:

curl -fsSL https://get-claude.dev.razorpay.in/setup.sh | bash
claude --version

If the same error persists after the fresh terminal, post in #ai-help with the exact error output. Do not copy the node node_modules/@anthropic-ai/claude-code/install.cjs path from the error unless support confirms the install location; global and local installs use different paths.

References. W.5, #ai-help thread 2026-06-26, #ai-help thread 2026-06-27, Tech IT routed thread.

D.11 — Unknown skill: login after running claude /login (status: fixed)

Symptom. You run claude /login from the shell and Claude Code prints Unknown skill: login, or you see Please run /login after another auth error and try to paste /login into the terminal command line.

Diagnosis. /login is an in-session slash command, not a shell subcommand. Running claude /login starts Claude Code with /login as the prompt text, so the harness tries to interpret it as a skill name. This is separate from the stale-Vertex 403 fix; if the same output also mentions aiplatform.googleapis.com, follow D.3 first.

Fix. For the standard Razorpay setup, do not run claude /login. Run the setup script, close old terminals, open a fresh terminal, then start Claude Code with claude and follow the browser SSO flow if prompted:

curl -fsSL https://get-claude.dev.razorpay.in/setup.sh | bash
claude

If a VS Code or extension session remains stuck after that, refresh Claude Code’s browser auth explicitly, then restart the editor:

claude auth logout
claude auth login

References. W.5 failure mode #9, #claude-onboarding-support thread 2026-04-01, #claude-onboarding-support thread 2026-04-01, #claude-onboarding-support thread 2026-04-01.

D.12 — thinking.signature or missing thinking block errors on Bedrock (status: workaround)

Symptom. Claude Code or the VS Code plugin returns a 400 with thinking.signature.str: Input should be a valid string, each thinking block must contain thinking, or Received Model Group=...-bedrock. The error can show up even when the model is enabled and your LiteLLM budget is fine.

Diagnosis. This is a request-shape problem, not a quota problem. Claude Code is sending an extended-thinking block that Bedrock validates more strictly than the normal chat path. A stale session, plugin window, or manual script that mutates message payloads can keep replaying the bad block.

Fix. Start a fresh Claude Code session or VS Code window first. If the error repeats, turn extended thinking off with /thinking off or the equivalent setting, then retry the prompt. Also confirm the model name is a current Razorpay LiteLLM route (claude-opus-4-8, not a stale Opus label) and update Claude Code if the same window keeps sending malformed thinking blocks. If you still need help, post the redacted full error and whether you were using terminal Claude Code or the VS Code plugin in #ai-help.

References. #ai-help Opus 4.8 Bedrock signature thread 2026-07-01, #ai-help missing thinking block response 2026-07-07, #ai-help Sonnet signature response 2026-07-07.

D.13 — LiteLLM account or model access is not enrolled (status: fixed)

Symptom. Claude Desktop or claude.ai access looks fine, and you may have already run the setup script, but Claude Code still says the LiteLLM account/key is not enrolled, the selected model is not enabled, or key_model_access_denied appears. In one recurring shape, the message starts with Please run /login, lists This key can only access models=[...], then ends with Tried to access <model>.

Diagnosis. The Claude.ai enterprise seat and the LiteLLM gateway key are separate gates. The setup script can write the local Claude Code configuration, but it cannot approve a missing LiteLLM enrollment or model grant by itself. When the error already lists enabled models, however, the key is enrolled: Claude Code has selected a default route outside that list. In that case, the /login banner is not the diagnosis.

Fix. Use this order:

1. If the error lists enabled models, run /model <exact-enabled-route> inside Claude Code using one of those names. Do not keep retrying /login.
2. If an approved route you need is absent, open https://llm-gateway.razorpay.com/auth/, click Add Models, enable it, wait two to three minutes for the gateway cache to refresh, then restart Claude Code.
3. If the account/key is not enrolled or an approved route cannot be enabled, post in #ai-help asking for LiteLLM gateway provisioning or model enablement.

To check usage later, open https://llm-gateway.razorpay.com/ui/?page=new_usage and log in with your Razorpay email plus the LiteLLM key as the password.

Do not solve this by hunting for a raw external OpenAI or Anthropic key. Standard Claude Code/OpenCode access should route through the Razorpay LiteLLM gateway; direct external API keys follow a separate CISO-approved request path only when a tool cannot use the internal gateway.

References. W.5 failure mode #5, #ai-help LiteLLM key request 2026-07-08, #ai-help LiteLLM enrolment response 2026-07-09, #ai-help Add Models response 2026-07-09, #ai-help default-model report 2026-07-11, #ai-help repeated model-list failures and selection fix 2026-07-14.

---

Layer 1 — Compass plugin

Problems with installing, verifying, or running the program-pinned plugin bundle: hook failures, version drift, skill discovery issues.

Escalation path: #ai-help. For plugin-development questions specifically, #testing-slash or the Compass plugin co-owners (Aravinth P K, Vaibhav Dhir).

Entries seed from cohort experience. If you have hit and solved one, contribute it using the format below.

---

Layer 2 — Design and dashboard

Problems with the Figma MCP, Blade compliance checks, the design preview platform, frontend tooling.

Escalation path: #design-system for Blade questions, #experience_fe_core for FE tooling.

Entries seed from cohort experience.

---

Layer 3 — Skills and agents

Problems with skill invocation, MCP server timeouts, agent loops, subagent handoff, custom agents built on the SDK.

Escalation path: #rzp-claude-skills for skill-discovery issues, #mcp-dev for MCP server issues, #ai-code-champions for craft questions.

D.14 — Prompt is too long or context fills at session start (status: workaround)

Symptom. Claude Code / Claude Cowork refuses a prompt with Prompt is too long, says the conversation is too long to continue, hits the context limit after only one or two prompts, or shows a large context-window jump even when the first message is just hi.

Diagnosis. This is context-window exhaustion, not a LiteLLM quota cap. The window includes your current prompt, earlier turns, files or logs the agent has read, RAG chunks, MCP/tool schemas, enabled plugin instructions, hooks, and system prompt material loaded at session start. Some startup payloads do not show as tool usage in /mcp, so a blank prompt can still be expensive if heavy tools are preloaded.

Fix. Use this order:

1. Start a fresh Claude Code / Cowork session and retry a minimal prompt such as hi.
2. If the minimal prompt works, reduce the original input: summarise earlier turns, split pasted docs or logs into smaller chunks, reduce RAG/file payloads, and ask the agent to read only the files needed for the current step.
3. Run /context to see what is filling the window. If the first turn is already large, temporarily disable unused MCPs, plugins, and session-start hooks; restart Claude Code; then re-enable them one at a time.
4. If /mcp shows zero usage but the window still jumps, inspect your ~/.claude/settings.json for enabled plugins, mcpServers, custom hooks, status-line commands, or auto-included prompts that may inject schemas at startup.
5. If a clean session with a minimal prompt still fails, run Claude Code with --debug, redact secrets from the initial prompt/system blocks, and post the exact error plus the redacted startup-context excerpt in #ai-help.

References. G.2 context-window mental model, #ai-help prompt-too-long thread 2026-06-11, #ai-help context-limit thread 2026-07-02, #ai-help startup-context thread 2026-07-07, #ai-help prompt-too-long thread 2026-07-09.

D.15 — Codex trial capacity or workspace usage is exhausted (status: workaround)

Symptom. Codex warns that you have used most of your allowance, says You've hit your usage limit. Contact your workspace owner for more access, reports a workspace spend cap, or repeatedly returns 429 Too Many Requests after usage warnings.

Diagnosis. This is the separate Codex workspace allocation, not your Claude Code LiteLLM budget. Re-running the Razorpay Claude setup, changing a LiteLLM model, or signing into Codex again will not reset a workspace-controlled cap. On 2026-07-21, #ai-help announced that Razorpay’s shared Codex trial credits were nearly exhausted and directed builders away from Codex until a seat-based plan is resolved. An expiry date or percentage shown earlier is not a promise of more capacity. A single bare 429 can instead be a short rate limit; retry once after a pause before treating it as a cap.

Fix. Use the current transition route:

1. Stop retrying Codex and keep the exact error text plus a short note on the unfinished task.
2. If you have already received Claude Team access, follow the migration SOP linked by support and continue there.
3. Otherwise, move the task to Claude or an enabled GPT route through LiteLLM, provided the relevant LiteLLM budget still has capacity. Run the normal Compass checks before shipping code.
4. If neither route is available or the work remains blocked, post in #ai-help with the error and blocked task. Follow the latest support instruction rather than requesting a specific Codex credit amount; the seat-based plan is still in progress.

References. Appendix A — Codex tool boundary, #ai-help shared-credit response 2026-07-15, #ai-help repeated cap response 2026-07-16, #ai-help no-increase response 2026-07-16, #ai-help Codex trial-exhaustion transition 2026-07-21.

D.16 — Claude Team or Max still uses the LiteLLM route after migration (status: fixed)

Symptom. Support provisioned Claude Team or directed you to Claude Max, but a fresh Claude Code session still reports llm-gateway.razorpay.com, a LiteLLM virtual key, or a LiteLLM model-cap error. A Team-only model may also stay unavailable even though you accepted the invite.

Diagnosis. Your Claude Code settings still contain the old LiteLLM provider overrides. Signing into the new subscription does not remove them, so the terminal keeps sending requests through the previous gateway route. This diagnosis applies only after support has explicitly migrated you; LiteLLM remains the correct route for everyone else.

Fix.

1. Confirm that support provisioned Team or Max and sent you the current migration SOP. If not, keep the LiteLLM setup and ask in #ai-help rather than changing providers.
2. Close active Claude Code sessions. Follow the SOP to remove the legacy LiteLLM and Anthropic provider overrides it names from ~/.claude/settings.json. Do not delete unrelated plugin, hook, or permission settings, and never paste the whole file into Slack.
3. Restart Claude Code and complete the login route in the SOP.
4. Verify a fresh session no longer reports the LiteLLM gateway before diagnosing the problem as a Team/Max model outage.
5. If it still uses LiteLLM, post the redacted provider/error line, the surface you used, and confirmation that you completed the SOP in #ai-help.

Do not use this fix to escape a LiteLLM quota. Team and Max are separately provisioned routes, not self-serve fallbacks.

References. Y.8 — choose your current route, #ai-help repeated fix 2026-07-09, #ai-help repeated fix and SOP 2026-08-19, #ai-help successful retry 2026-08-24.

---

Layer 4 — Infrastructure (devstack)

Problems with internal infrastructure that the program depends on: CI, deploy, internal proxy, secrets management, the devstack itself.

Note. Most Layer 4 problems are out of scope for this appendix; they belong to the devstack team. Entries here cover the interaction between AI workflows and the devstack.

Escalation path: #devstack-onboarding-support.

Entries seed from cohort experience.

---

Entry format

Each entry follows this shape:

### D.N — <Title> (status: open / fixed / workaround)

<div class="pb-card">

**Symptom.** What the user sees, in plain language.

**Diagnosis.** What is actually happening, with the diagnostic steps to confirm.

**Fix.** The known fix. Step-by-step. Exact commands.

**References.** PRs, RFCs, related chapters, Slack thread, or external links.

---

Contribution flow

The contribution flow:

1. Hit a problem in your daily work.
2. Solve it (or get it solved by escalating to the layer’s path).
3. Write up the entry using the format above. The fix block must be copy-pasteable.
4. Open a PR against this appendix. Branch name: docs/known-issue-<short-slug>.
5. The cohort lead reviews monthly; entries merge in batches.

A fix that lives only in a Slack thread evaporates within months. A fix that lands here helps every next builder.

---

Cross-references

• W.5 — Installing the stack, the canonical reference for Layer 0 failure modes.
• W.4 — Your auth setup, the mental model for the five auth layers.
• W.6 — The LLM Gateway, what the gateway does.
• Appendix F — Slack Channels, the escalation channel directory.
• Prologue §0.4 — The Enablement Stack, which defines the layers used here.

---

Last reviewed: 2026-08-25. Cadence: monthly cohort-lead review for the first six months; quarterly thereafter.