All docs

Troubleshooting

Common issues and their solutions. Check logs first with squeezr logs, then look for your issue below.

502 errors / Claude Code can't reach the API

Symptoms

  • Claude Code reports a 502 Bad Gateway or connection error.
  • The proxy is running but requests fail.

Most likely cause: HTTPS_PROXY set globally

If HTTPS_PROXY is set in your global environment (e.g. via setx on Windows or in your shell profile), it routes all HTTPS traffic — including Claude Code — through the MITM proxy on port 8081, which is only designed for Codex WebSocket traffic. This will cause 502s for Claude Code.

Fix: remove HTTPS_PROXY from your global environment. Only set it per-session in the terminal where you run Codex:

# Windows — remove the global registry entry
reg delete HKCUEnvironment /v HTTPS_PROXY /f

# Then set only when running Codex
$env:HTTPS_PROXY = "http://localhost:8081"
codex

Proxy not running

Symptoms

  • Your coding tool reports a connection error or timeout.
  • squeezr status shows "not running".

Solutions

  1. Start the proxy: squeezr start
  2. Verify Node.js version: node --version (must be 18+; Node.js 24 is supported).
  3. Check logs for errors: squeezr logs

Port conflicts

Symptoms

  • Error: listen EADDRINUSE: address already in use :::8080

Solutions

  1. Stop any existing Squeezr process: squeezr stop, then squeezr start.
  2. Change the port interactively: squeezr ports
  3. Or edit squeezr.toml:
    [proxy]
port = 9090
mitm_port = 9091

Env vars not applying after setup/update

Symptoms

  • After squeezr setup or squeezr update, the old ANTHROPIC_BASE_URL is still active.
  • Claude Code goes directly to the Anthropic API, bypassing Squeezr.

Solutions

  1. Open a new terminal. The shell wrapper installed by squeezr setup auto-refreshes env vars, but only after the wrapper is loaded. If you just ran setup for the first time, open a new terminal once to activate it.
  2. Or source your shell profile manually:
    # bash/zsh
source ~/.bashrc

# PowerShell
. $PROFILE

Stale "update available" banner after squeezr update

Symptoms

  • After running squeezr update, the proxy still shows the old version or the update banner keeps appearing.

Solutions

  1. Run squeezr stop then squeezr start to ensure the new binary is running.
  2. If problems persist, do a clean reinstall:
    squeezr uninstall
npm uninstall -g squeezr-ai
npm install -g squeezr-ai
squeezr setup
squeezr start

Codex TLS certificate errors

Symptoms

  • Codex reports a certificate error when connecting to chatgpt.com.
  • TLS handshake failure in Codex logs.

Solutions

  1. Re-run setup to reinstall the CA certificate:
    squeezr setup
  2. On Windows, the CA is imported into the Windows Certificate Store. Restart Codex after setup if the certificate was just installed.
  3. On macOS/Linux/WSL, verify NODE_EXTRA_CA_CERTS points to the bundle:
    echo $NODE_EXTRA_CA_CERTS
# should print ~/.squeezr/mitm-ca/bundle.crt

Node.js v24 compatibility

Squeezr is fully compatible with Node.js v24. If you see UND_ERR_NOT_SUPPORTED errors with older versions of Squeezr, update to the latest version:

squeezr update

Compression too aggressive

Symptoms

  • The model asks to re-read files it should have in context.
  • The model misses errors or important details in compressed output.

Solutions

  1. Raise the compression threshold (compress less):
    [compression]
threshold = 1500
  2. Skip specific tools:
    [compression]
skip_tools = ["Read"]
  3. Disable adaptive compression:
    [adaptive]
enabled = false
  4. Skip compression for a single command by adding # squeezr:skip to the Bash command.

Getting help

If none of the above solutions work:

  1. Run squeezr logs and copy the relevant output.
  2. Check your env vars: echo $ANTHROPIC_BASE_URL
  3. Open an issue on GitHub with the log output, your config (with API keys removed), and a description of the problem.