Troubleshooting

Error "forge not found" After Install

forge binary not on PATH

Cause: The Forge binary was installed but your shell's PATH doesn't include the install directory. This is the most common post-install issue.

Fix:

• Check where Forge was installed: which forge or ls ~/.forge/bin/forge
• If found, add the install directory to your PATH in ~/.zshrc or ~/.bashrc:

• If Forge is not found at all, re-run the install script:

Sidekick installed but forge binary was not

Cause: The Sidekick plugin was installed in Claude Code but the Forge binary itself was never installed on your machine. Sidekick needs both the plugin and the Forge binary.

Fix: Follow the full install sequence in Getting Started → Installation. Install the Forge binary first, then install the Sidekick plugin.

Error Health Check Failures

✗ ForgeCode not reachable via OpenRouter

Cause: Invalid API key, no network access, or OpenRouter service issue.

Fix:

• Verify your key at openrouter.ai/keys
• Check your key is in ~/forge/.credentials.json under api_key
• Confirm provider and model are set in ~/forge/.forge.toml
• Confirm you have credits — free tier has rate limits

✗ Model not available

Cause: The forge/forge-code model is temporarily unavailable or your account tier doesn't include it.

Fix: Check openrouter.ai/models for availability. If unavailable, wait and retry — ForgeCode has high uptime.

✗ Bootstrap skills not loaded

Cause: .forge/skills/ directory is missing or corrupted.

Fix: Reinstall Sidekick to restore bootstrap skills:

Config OpenRouter Configuration

API key set but not persisting

Cause: ~/forge/.credentials.json may not have been written correctly.

Fix: Check if ~/forge/.credentials.json exists and contains an api_key field. If not, follow the STEP 0A setup in skills/forge.md to recreate it.

Wrong model being used

Fix: Edit .forge.toml and set model = "forge/forge-code" explicitly. Other models may not have Forge's agentic coding capabilities.

Error 429 Rate Limit from Forge

Too many requests — OpenRouter rate limit hit

Cause: Your OpenRouter account has hit its per-minute or per-day request limit. Free tier accounts have much lower limits than paid accounts.

Symptoms: Forge returns a 429 error mid-task, or the health check fails with a rate limit message.

Fix:

• Wait 60 seconds and retry — per-minute limits reset quickly
• If you hit daily limits frequently, upgrade your OpenRouter account at openrouter.ai/credits
• Switch to MiniMax provider if it has better rate limits for your usage pattern (see Provider Config)

Error 402 Payment Required

OpenRouter account has no credits

Cause: Your OpenRouter account balance is zero or below the minimum required to run the forge/forge-code model. This model is not on the free tier.

Symptoms: Health check passes (credentials valid) but the first task delegation immediately returns 402.

Fix:

• Add credits to your OpenRouter account at openrouter.ai/credits
• A small top-up ($5–10) is typically enough for extensive Forge usage
• After adding credits, rerun /forge — the health check will confirm the model is now accessible

Behavior Forge Stuck in a Loop

Forge keeps repeating the same action without progress

Cause: Forge entered a loop — typically trying the same fix repeatedly, or oscillating between two states. This is a known edge case in agentic coding systems when the DESIRED STATE is ambiguous or the SUCCESS CRITERIA is underspecified.

Symptoms: Forge output shows the same file being edited multiple times with no net change, or the same error appearing after each attempt.

Fix:

• Interrupt the current task by telling Claude: "Forge is looping — trigger L3 takeover"
• Claude will lift the delegation restriction, implement the task directly, and produce a DEBRIEF
• The DEBRIEF's AGENTS_UPDATE field will add instructions to AGENTS.md to prevent the loop pattern on similar future tasks

Forge loops on test failures

Cause: Forge is trying to fix a failing test but the test itself has a bug, or the test expects behaviour that conflicts with what's in AGENTS.md.

Fix: Tell Claude: "The test has a bug, not the implementation." Claude will inspect both, fix the root cause, and update AGENTS.md with the correct testing pattern.

Behavior Fallback Ladder Not Triggering

Forge failed but Claude didn't escalate

Cause: The failure signal wasn't in one of the three recognized patterns (error output, wrong output, stall).

Fix: Describe to Claude what went wrong — "Forge's output doesn't satisfy the success criteria because…". Claude will manually trigger the fallback ladder from the appropriate level.

L1 retry produced the same wrong output

This is expected — L1 is a single retry with a reframed prompt. If L1 fails, the ladder escalates to L2 automatically. If you see Claude not escalating after L1 fails, say "that's still wrong, escalate to L2".

L3 takeover didn't produce a DEBRIEF

Fix: Ask Claude explicitly: "Please produce a DEBRIEF for this L3 takeover." The DEBRIEF (TASK / FORGE_FAILURE / LEARNED / AGENTS_UPDATE) should always follow an L3 takeover.

Behavior AGENTS.md Issues

New instructions not being added to AGENTS.md

Cause: The deduplication check found a semantically similar entry already exists.

This is correct behavior — the dedup prevents duplicate entries. If you believe the new instruction is genuinely different, ask Claude to add it with explicit phrasing that distinguishes it from existing entries.

AGENTS.md bootstrapped with wrong content

Fix: Edit ./AGENTS.md directly — it's a plain Markdown file. Remove incorrect entries and add your project's actual conventions. Claude will use your edits on the next /forge invocation.

~/forge/AGENTS.md not found

The global AGENTS.md at ~/forge/AGENTS.md is optional. If it doesn't exist, Claude creates it on the first cross-session write. No action needed.

Recovery Session Recovery

Forge session appears stuck / Claude is confused about state

Fix: Deactivate and reactivate Forge:

After an L3 takeover, delegation isn't resuming

After L3, Claude returns to delegation mode automatically for the next task. If Claude seems to be implementing directly instead of delegating, say "re-enter Forge delegation mode" — it will reload the delegation protocol from SKILL.md.

Reset Reinstall / Full Reset

To do a clean reinstall of Sidekick (preserves AGENTS.md and session logs):

To fully reset your API credentials (e.g. to change your API key):