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.

Usage Policy violation errors

Symptoms

  • Claude Code shows: "Claude Code is unable to respond to this request, which appears to violate our Usage Policy"
  • Every message in a long session triggers the error.

Cause

Squeezr's stale-turn summarization (active in long sessions) inserts placeholder text into old messages. Before v1.67.3, this placeholder included special Unicode characters and keywords extracted from your code (file paths, error names) which Anthropic's safety filters flagged as a prompt-injection pattern. Upgrade to v1.67.3+ to fix this permanently.

Immediate workaround (if you can't upgrade)

  1. Start a new Claude Code session — fresh sessions don't have stale-turn placeholders.
  2. Or disable stale turns in ~/.squeezr/squeezr.toml:
    [compression]
stale_turns = false
    Then squeezr restart.

Prompt Cache Hit Health below 80%

Symptoms

  • Dashboard shows Hit Health % below 80% or dropping mid-session.
  • Costs are higher than expected despite compression being active.

Cause

Anthropic caches your conversation prefix (tools + system + old messages). If anything changes that prefix between requests, Anthropic re-bills it at full price. Hit Health measures how often you're reading from cache vs creating (paying to cache) new tokens.

Normal behaviour

A new session starts at 0% and reaches ≥80% by the 2nd–3rd message as the prefix stabilises. This is expected. If it drops mid-session, something is mutating the prefix.

Common causes and fixes

  1. Adaptive threshold shifting — The compression threshold changes with context pressure, compressing different blocks each request. Fixed in v1.67.4 (threshold is frozen when cache markers are present).
  2. Stale-turns boundary moving — Each new turn shifts which messages are "stale", producing different output. Fixed in v1.67.1+.
  3. AI compression non-determinism — AI backends can return slightly different text for the same input. Fixed by the cache barrier: AI only runs on new messages, not on the cached prefix.
  4. Old session with corrupt placeholders — Start a new Claude Code session.

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.