Troubleshooting

Install / command not found

Symptom: forgeax: command not found

• Confirm the package: npm ls -g @forgeax/cli
• Ensure npm’s global bin is on PATH: npm prefix -g → …/bin
• Temporary: npx @forgeax/cli --version

Even --demo fails

• Confirm Node ≥ 18: node -v
• Reinstall: npm uninstall -g @forgeax/cli && npm install -g @forgeax/cli
• From source/tarball: ensure dist/ is built and bin points at dist/cli/main.js

API / model errors

Symptom	Likely cause
Missing key	ANTHROPIC_API_KEY unset (or OPENAI_API_KEY for openai-compat)
404 DeploymentNotFound	Model name treated as a gateway deployment; try FORGEAX_PROVIDER_API=openai-compat with a correct OPENAI_BASE_URL
401 / 403	Bad key or wrong base URL environment
Empty response / timeout	Gateway rate limits or proxy truncation; try another --model or check ANTHROPIC_BASE_URL

Without a key, start with:

forgeax --demo -p "hi"

TUI glitches / garbled text

forgeax --no-tui
# or
export FORGEAX_NO_TUI=1

Prefer UTF-8 terminals; on SSH / minimal environments, use readline first.

Constant permission prompts / denials

• Inspect .forgeax/settings.json permissions.deny / ask
• Confirm you did not set --permission-mode bypassPermissions while root / killswitch refuses startup
• Shell rules are structure-aware: allow Bash(git *) does not cover a trailing && rm

MCP tools missing

See MCP troubleshooting. First run the server command locally by hand.

Cannot resume a session

ls .forgeax/sessions/
forgeax --resume <id>
# or
forgeax -c

Confirm --sessions-dir matches last time; a brand-new id with an empty WAL will not “fake resume”.

Sandbox unavailable

--sandbox needs platform tooling:

• macOS: sandbox-exec
• Linux: bwrap

Missing tools degrade loudly — do not assume isolation.

Still stuck

1. Collect version: forgeax -h / forgeax -v
2. Minimal repro: --demo, then a real-key -p
3. Open an issue: ForgeaX-Games/forgeax-cli

Include: OS, Node version, full command line (redact keys), relevant settings snippets (no secrets).