Troubleshooting

Start with notdiamond doctor - it runs automated health checks and usually points to the problem.

Start here:

notdiamond doctor

Checks:

✓ Config file exists and is valid JSON
✓ Binary is installed and on PATH
✓ Local port (default 8082) is available
✓ Auth token is valid and not expired
✓ Cloud endpoints are reachable

If any check fails, doctor prints the issue and often suggests a fix. Run this first for any problem.

Common Issues

Proxy starts but Claude Code doesn’t route through it

Symptom: notdiamond start succeeds, but notdiamond logs -f shows no requests.

Diagnosis: Claude Code is not configured to use the proxy. The proxy only intercepts requests sent to http://127.0.0.1:8082.

Fix: Make sure you’re running notdiamond claude, not claude directly.

notdiamond claude      # correct: uses proxy
claude                 # incorrect: bypasses proxy

If you aliased claude="notdiamond claude" in your shell run commands, restart your shell session for the alias to take effect.

`auth rejected on /v1/ingest` error

Symptom: Logs show repeated 401 Unauthorized errors when posting to /v1/ingest.

Diagnosis: Your auth token is invalid or expired. Tokens last 60 days. The proxy refuses to start without valid credentials.

Fix:

notdiamond login       # re-authenticate (device-code flow, opens browser)
notdiamond restart     # restart the proxy

Port 8082 already in use

Symptom: notdiamond start or notdiamond claude fails with “address already in use” or “EADDRINUSE”.

Diagnosis: Another process is listening on port 8082.

Fix: Either kill the other process, or reconfigure the proxy to use a different port:

notdiamond config edit        # opens config.json
# Change "port": 8082 to "port": 8083 (or any free port)
notdiamond restart            # start on the new port

To find what’s using the port:

# macOS/Linux
lsof -i :8082

# Windows
netstat -ano | findstr :8082

`EACCES: permission denied` on `npm install -g` (macOS/Linux only)

Symptom: Install fails with permission error.

Diagnosis: Your global npm prefix is a system directory you don’t own (e.g., /usr/local).

Fix: Either use sudo, or reconfigure npm’s global prefix to a directory you own (recommended):

# Quick fix: use sudo
sudo npm install -g <tarball>

# Better: configure npm prefix
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
export PATH=~/.npm-global/bin:$PATH    # add to ~/.zshrc or ~/.bashrc
npm install -g <tarball>               # now this works without sudo

Symptom: notdiamond claude fails with “token expired” or similar.

Diagnosis: Your 60-day auth token has expired.

Fix:

notdiamond login       # re-authenticate (opens browser)
notdiamond restart     # restart the proxy

Reading logs

notdiamond logs -f     # tail the last 100 requests, follow new ones (Ctrl+C to exit)

Log output format:

2026-05-25 10:15:23 | duration_ms=145 | requested=claude-opus-4-7 | routed=claude-sonnet-4-6 | savings=$0.15
2026-05-25 10:15:24 | duration_ms=892 | requested=claude-opus-4-7 | routed=claude-opus-4-7 | savings=$0.00 | (tools present)
2026-05-25 10:15:25 | duration_ms=87 | ERROR: auth token expired

Fields:

timestamp - when the request arrived
duration_ms - how long it took
requested - the model Claude Code asked for
routed - the model the router chose
savings - estimated cost difference (Claude’s cost - routed cost)
ERROR - if present, what went wrong

If you see repeated errors, run notdiamond doctor to diagnose.

Full proxy logs

The proxy also writes to ~/.notdiamond/proxy.log (macOS/Linux) or %USERPROFILE%\.notdiamond\proxy.log (Windows).

Useful for:

Startup failures (port binding, config parse errors)
Authentication errors
Unexpected crashes

Tail with:

# macOS/Linux
tail -f ~/.notdiamond/proxy.log

# Windows PowerShell
Get-Content -Path $env:USERPROFILE\.notdiamond\proxy.log -Tail 20 -Wait