Skip to main content

​
Troubleshooting

Start with these checks:
cmx status checks the local gateway. cmx harness verify checks managed client routing. Neither proves a provider answered a request. After connecting, restart the coding client, send a normal request, and compare cmx stats before and after.

​
cmx is not found

Open a new terminal so the installer’s PATH change takes effect. On Linux and macOS, the standalone executable is normally in /usr/local/bin or ~/.local/bin. On Windows, the PowerShell installer uses %LOCALAPPDATA%\CMX\bin. Check whether the file exists and whether that directory is on your user PATH. If multiple copies exist, inspect command -v cmx on Unix or Get-Command cmx in PowerShell.

​
The installer did not get an answer

The standalone installer starts cmx setup --ask-connect-ready. Run that command again in an interactive terminal. You should see the ready provider list and the y/N prompt. An unavailable or closed terminal is an error, not consent. If you choose n, use cmx providers <client> list, then cmx providers <client> connect <id> later, or open cmx and use CONFIG.

​
No provider is ready

A detected executable does not necessarily mean it is signed in. Sign in through the native client’s own command, then run cmx providers <client> list again. Claude Code readiness may require ANTHROPIC_API_KEY in the environment; Aider readiness checks OPENAI_API_KEY or ANTHROPIC_API_KEY. Antigravity CLI detection can precede its interactive sign-in. Follow the client-specific guide.

​
The client cannot reach the provider

  1. Check cmx status and start the gateway with cmx start if needed.
  2. Check cmx harness verify and the client’s native provider login.
  3. Restart the client to reload its settings.
  4. Send a request, then look for a new request in cmx stats.
If stats increase but the provider still rejects the request, check the native provider account, model name, quota, and endpoint. If stats do not increase, inspect the client’s selected base URL or route using its connection guide. For custom clients, verify that they append paths correctly to the base URL.

​
stop or uninstall refuses to restore a client

CMX protects against leaving a client pointed at a stopped gateway. It keeps the gateway running and reports which client file conflicted or could not be read. Inspect that file and its CMX restore sidecar, preserve any user edits, then retry cmx stop or cmx uninstall. Do not kill the gateway or delete the backup first. If you need help, share the error message and command output after removing paths and secrets; do not share provider keys or entire client config files.

​
CMX started and a client reconnected

A normal cmx start can reconnect routes previously restored by cmx stop when the direct client settings are unchanged. To stay direct, run cmx providers <client> disconnect <id> or cmx harness disable <client> while CMX is running, then stop it. An explicit n to cmx setup --ask-connect-ready also clears a pending reconnect.

​
Traffic appears, but savings are zero

This can be expected. The request may be short, contain no eligible older context, use a native format that is only proxied, or fail the cost or policy checks. OpenAI Responses requests with previous_response_id bypass summarization. Inspect How compression works and Token savings. Compare actual cost in your provider’s billing portal.

​
Check local diagnostics safely

cmx logs explains what diagnostics are available; CMX does not capture raw prompts and responses. cmx permissions checks owner-only CMX directory permissions. Before sharing cmx doctor output or a config excerpt, remove personal paths, account identifiers, tokens, and provider credentials.
Last modified on September 24, 2026