Troubleshooting

If something's broken, start here. Most issues fall into install, auth, or proxy/billing buckets.

brew install uv && uv tool install fredcode

Install issues

pip: command not found (pyenv users)

pyenv global 3.13 makes pip available, OR (recommended) install uv:

brew install uv && uv tool install fredcode

uv ships its own Python and isolates each tool in its own venv — no PATH gymnastics, no global Python required.

pip install fails with PEP 668 externally-managed-environment

Modern macOS/Linux Python ships with a marker that blocks global pip installs. Use uv or pipx; both create isolated venvs:

# Recommended:
brew install uv && uv tool install fredcode

# Or pipx:
brew install pipx && pipx install fredcode

pipx install fredcode fails with ensurepip error

Homebrew's bottle for Python 3.14 has a broken ensurepip. Workaround:

# Either: switch to uv (cleanest)
brew uninstall pipx
brew install uv && uv tool install fredcode

# Or: manual venv with Python 3.13
python3.13 -m venv ~/.fred-venv
~/.fred-venv/bin/pip install fredcode
ln -s ~/.fred-venv/bin/fred ~/.local/bin/fred

fred: command not found after install

PATH probably doesn't include the install location. Run pipx ensurepath or uv tool ensurepath and restart your shell. If you used a manual venv, symlink:

ln -s <venv>/bin/fred ~/.local/bin/fred

Make sure ~/.local/bin is on your PATH (it usually is on modern shells, but not always).

Auth issues

Browser doesn't open during fred login

Use the device-code flow for headless boxes or stubborn default browsers:

fred login --device-code

fred prints a code, you enter it at https://app.fredcode.net/activate from any device, and the CLI continues.

Login timed out after 10 minutes

The localhost callback at port 41257 was blocked. Common causes:

• VPN intercepting localhost traffic.
• Another process bound to 41257 (run lsof -i :41257 to check).
• Firewall blocking inbound on the loopback interface.

Fall back to fred login --device-code — no localhost callback needed.

401 invalid_api_key

The key is wrong or stale. Issue a new one:

fred logout && fred login

401 revoked_api_key

Someone (you?) revoked the key in the dashboard. Re-login to get a fresh one. If you didn't revoke it yourself and you don't recognize the action, change your account password and re-login from there.

request_id mismatch — possible cross-site interference

Another browser tab opened a competing OAuth dance. Close other tabs and retry. This is the auth flow detecting that a different login attempt's callback hit your terminal — the CLI refuses to accept the wrong session for safety.

Billing / proxy issues

402 insufficient_credits

Top up at /billing. Existing transcript is preserved in memory; the next prompt after top-up will work.

400 unknown_model

You're trying a model not in the allowlist. Currently only deepseek-v4-flash and deepseek-v4-pro. Check what's set:

> /model

Switch with /flash or /pro, or set FRED_MAIN_MODEL=deepseek-v4-flash in your env.

400 missing_model

Request body didn't include a model field. The CLI sets this automatically; you'll only see this when calling the proxy directly with a bare HTTP client.

429 rate_limited

Either IP rate (120/min) or per-user (60/min). Wait the duration in the Retry-After response header. The CLI surfaces this as a friendly message; it doesn't auto-retry to avoid stampeding when you've already hit a limit.

502 upstream_unreachable

DeepSeek didn't respond. Try again; if persistent, check status.deepseek.com. Our proxy doesn't bill for failed upstream calls — the usage_events row only writes after a successful response.

REPL issues

Streaming flickers in tmux / Windows Terminal

rich.Live doesn't always play nicely with tmux's redraw model or Windows Terminal's renderer. Disable it:

fred --no-stream

Falls back to a plain transcript — same content, no live region. Slightly less pretty, much less flicker.

Banner shows system Python warning

Harmless; the CLI works fine. The warning is a nudge that you're running against the OS-managed Python (which can break on system updates). Switch to a venv or pyenv to make it go away — or ignore it forever, your call.

Out of credits during a session

Buy more, then continue. Existing transcript is preserved in memory; the next prompt will work after you've topped up. No need to restart the session.

Telemetry issues

psycopg import error

Telemetry is an optional extra. Either install it:

pip install fredcode[telemetry]

Or unset DSC_TELEMETRY_DB_URL so Fred doesn't try to load the driver. See /docs/telemetry for the full setup.

Permission issues

Same prompt over and over

Hit a instead of y at the panel — that persists an allow rule to ~/.dsc/settings.local.json so it doesn't repeat next session. See /docs/permissions-and-yolo for the full rule grammar.

Bash command failing with sandbox-exec: in stderr

The macOS sandbox denied the operation. Either:

• Loosen the sandbox: /sandbox full in the REPL, or restart with --sandbox full.
• Move the work inside cwd so workspace-write covers it.
• Run the command yourself outside Fred — sometimes that's simpler than reasoning about the profile.

Checkpoint issues

/restore doesn't change anything

Empty /checkpoints output usually means no write tools have run this session yet (or DSC_CHECKPOINTS=0 is set). The shadow repo only commits after a successful write.

Shadow repo using too much disk

Delete ~/.dsc/checkpoints/ entirely. It'll regenerate on your next session, minus the history. Or set DSC_CHECKPOINTS=0 for monorepos where the cost outweighs the benefit. See /docs/checkpoints.

Still stuck?

File an issue:

• github.com/nwhitley-trAIner/fred/issues

Include in the report:

• fred --version output
• Your OS + version (sw_vers on macOS, uname -a on Linux)
• The exact command you ran
• The full error output (no truncation — paste in a code block)
• For auth issues, the contents of ~/.config/fred/credentials.json with the API key field redacted

Or DM the maintainer if you have a back-channel — but the GitHub issue tracker is the best place to get a useful answer with witnesses.