Troubleshooting

Most issues fall into a handful of buckets.

Install fails

SHA256 mismatch during install.

The tarball didn't match the pinned hash. Either:

Stale installer (re-run the install URL - it always fetches the latest with matching pin).
HTTPS-layer corruption (rare). Retry.

isonforge: command not found after install.

PATH didn't refresh. Open a new terminal window, or:

source ~/.bashrc       # bash
source ~/.zshrc        # zsh
exec fish              # fish

On Windows, close PowerShell completely and open a fresh window so the user PATH env reloads.

Windows: npm.ps1 cannot be loaded because running scripts is disabled.

PowerShell execution policy blocks .ps1 scripts. IsonForge's own installer uses npm.cmd internally to avoid this, but if you hit it in another context:

Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

Node.js installation failed.

The installer relies on your package manager (apt, dnf, brew, winget). If that fails, install Node 18+ manually from nodejs.org and re-run the IsonForge installer.

Browser doesn't open.

The CLI prints a URL. Open it manually in any browser, sign in, return to the terminal. The CLI polls for the session.

Login times out (5 min).

Network reachability between you and isonai.net. Try --manual:

isonforge auth login --manual

Generate a key from the dashboard, paste it.

No API key configured.

Either:

You never logged in - run isonforge auth login.
Config got wiped - check ~/.isonforge/config.json exists.
Env var overriding incorrectly - unset ISONFORGE_API_KEY if set.

REPL doesn't start

Failed to start interactive REPL.

Usually Node version. Check:

node --version

Must be 18+. Update via your installer.

Stuck on splash screen.

Could be model warming up. Check:

/doctor

Reports node, gateway, key, FORGE.md status.

Streaming hangs

Thinking... for >2 minutes.

The model is in deep reasoning. Hit Ctrl+C if you want to abort. Otherwise wait - very long thinking is normal for max effort or complex prompts.

If it hangs >5 min, the backend may be overloaded. Retry:

/clear
[your prompt]

Stream stops mid-response.

Server-side disconnect. The partial response is saved. Type "continue" or re-prompt.

Permission prompts won't stop

Same prompt over and over for safe operations.

Switch modes:

Shift+Tab     # cycle to acceptEdits or auto

Or set persistent rules in ~/.isonforge/permissions.json:

{
  "preset": "auto",
  "rules": [
    {"tool": "bash", "args_pattern": "git status*", "action": "allow"},
    {"tool": "bash", "args_pattern": "pnpm test*", "action": "allow"}
  ]
}

Wanted to approve, hit "No" by accident.

Just re-prompt the agent: "retry the previous bash call." The model has the failure in context.

Tool errors

Edit failed: old_string not found.

old_string must match the file exactly (whitespace + indentation). The agent will usually retry with a wider context match. If it keeps failing, the file may have been modified externally - /clear and try again.

Bash timeout.

Default 60s, max 300s. For long commands, the agent should set run_in_background=true automatically. If it didn't, prompt: "use run_in_background for the dev server."

Path outside project root.

The agent tried to read/write outside the working directory. Either:

Use --add-dir <path> to whitelist additional dirs.
Use absolute paths (the agent has full filesystem access in CLI by default; this is just a guidance check).

Sub-agent doesn't return

task_explore runs forever.

Sub-agents have a hard cap (8 iterations default, 12 max). If you see this in --verbose, the sub-agent is making slow tool calls (network, large file reads). Wait for the iteration cap.

Sub-agent returns "no results".

The prompt to the sub-agent may have been too vague. Be more specific:

> use task_explore to find every file that imports the `db` module from src/db.ts

vs:

> map the codebase

MCP servers don't connect

/mcp shows error state.

The server process failed to spawn or speak MCP correctly. Inspect:

isonforge --verbose 2>&1 | grep -i mcp

Common causes:

Command not found (check which <mcp-server>).
Environment variable not exported (echo $GITHUB_TOKEN).
Wrong stdio behavior (the server prints non-MCP output to stdout).

Background agents lost

isonforge agents shows stopped agents I didn't stop.

Process crashed. Check:

isonforge logs <id>
cat ~/.isonforge/agents/<id>/stderr.log

Common causes:

API key expired.
Network error.
Backend overload.

Restart with isonforge respawn <id> (note: doesn't preserve conversation state).

Settings not taking effect

~/.isonforge/settings.json field ignored.

Check spelling - JSON keys are case-sensitive.
Verify load with --verbose.
A flag may be overriding (flags always win).
File may be invalid JSON - try jq . ~/.isonforge/settings.json to validate.

Hook not firing.

Check matcher regex matches your tool names.
Confirm the hook command runs standalone: echo '{}' | <your-hook-command>.
Check exit codes - non-zero with verbose stderr should appear.

/upgrade hangs

Self-update doesn't progress.

Wrap script may be missing or broken. Force-reinstall:

rm -rf ~/.isonforge/cli
curl -fsSL https://www.isonai.net/install-forge | bash

Skills not detected

/skills shows empty when I have a SKILL.md.

Verify the directory structure: ~/.isonforge/skills/<name>/SKILL.md (note: subdirectory, then SKILL.md, not a flat file).
Project Skills must be in the git repo root or walked-up parent dirs.
Frontmatter must be valid YAML between --- markers.
Check spelling - skill names are case-insensitive but [a-z0-9_-]+ only.

Diagnostic: `/doctor`

When in doubt:

/doctor

Reports:

Node version
IsonForge CLI version
Gateway reachability
API key status
FORGE.md presence
Recent error counts
Loaded settings sources

Most issues surface here first.

Still stuck?

Search github.com/IsonAI/isonforge/issues.
Run with --verbose and capture the output - useful when asking for help.
Email: support@isonai.net