# Troubleshooting

## Installation issues

macOS:

central cannot be opened because it is from an unidentified developer
: 1.  Right-click (or `Ctrl+Click`) the `central` binary.
:
: 2.  Select Open from the context menu.
:
: 3.  Click Open in the dialog.
:
:
:
: Or remove the quarantine attribute:
:
:
:
:
:
:
: ```BASH
: xattr -dr com.apple.quarantine ./central
: ```

central is damaged and can't be opened
: The quarantine attribute wasn't fully removed:
:
:
:
:
:
:
: ```BASH
: xattr -cr ./central
: chmod +x ./central
: ```

Linux:

Permission denied
: Make the binary executable:
:
:
:
:
:
:
: ```BASH
: chmod +x ./central
: ```

Windows:

SmartScreen blocked the app
: 1.  Click More info on the SmartScreen dialog.
:
: 2.  Click Run anyway.
:
:
:
: Or unblock via PowerShell:
:
:
:
:
:
:
: ```POWERSHELL
: Unblock-File -Path .\central.exe
: ```

central: command not found
: The binary is not on your `PATH`. Connected agents run into the same thing, because they start the proxy by running `central` themselves. Add the directory holding the binary, `~/.local/bin`, to your `PATH`:
:
:
:
:
:
: macOS / Linux:
:
:
: Append this line to your shell profile (`~/.zshrc` for zsh, `~/.bashrc` for bash), then open a new terminal:
:
:
:
:
:
:
: ```BASH
: export PATH="$HOME/.local/bin:$PATH"
: ```
:
:
:
: Windows:
:
:
: Run this in PowerShell, then open a new terminal:
:
:
:
:
:
:
: ```POWERSHELL
: [Environment]::SetEnvironmentVariable("Path", $env:Path + ";$HOME\.local\bin", "User")
: ```
:
:
:
:
:
:
: To confirm the binary is found:
:
:
:
:
:
:
: ```BASH
: central --version
: ```

## Login issues

Browser doesn't open
: If JetBrains Central CLI doesn't open your browser automatically, copy the URL from the terminal and paste it into your browser manually.

License check failed
: Your JetBrains Account doesn't have an active AI subscription.

OAuth callback fails
: Make sure port `19515` is available. JetBrains Central CLI uses this port for the OAuth callback server.
:
: macOS / Linux:
:
:
:
: ```BASH
: lsof -i :19515
: ```
:
:
:
: Windows:
:
:
:
: ```POWERSHELL
: netstat -ano | findstr :19515
: ```

## Proxy issues

Proxy won't start
: The proxy port is assigned per machine and stored as `proxy_port` in `~/.jetbrains-central/config.json`; `central status` reports the one in use. Make sure that port is available — substitute it for `<port>`:
:
:
:
: macOS / Linux:
:
:
:
: ```BASH
: lsof -i :<port>
: ```
:
:
:
: Windows:
:
:
:
: ```POWERSHELL
: netstat -ano | findstr :<port>
: ```
:
:
:
:
: If you need that port for something else, set a different one with `central config set port <port>` or the `WIRE_PROXY_PORT` environment variable.
:
:
:
: If JetBrains Central CLI reports the proxy is running, but it's not responding, the PID file may be stale:
:
:
:
:
: ```BASH
: # Check if the process is actually running
: ps aux | grep central
:
: # If not, remove the stale PID file
: rm ~/.jetbrains-central/proxy.pid
: ```

Proxy stops unexpectedly
: Check the daemon log files for errors:
:
:
:
:
:
:
: ```BASH
: ls ~/.jetbrains-central/logs/
: cat ~/.jetbrains-central/logs/wire_$(date +%Y-%m-%d).log
: ```
:
:
:
: Log files are kept for two days and rotated daily. Set `log_level` to `debug` in JetBrains Central CLI settings for more details.
:
:
:
: You can also open the logs directory from the interactive interface: Settings > Show Logs.

## Agent issues

Claude Agent:

Auth conflict warning on startup
: If Claude Agent shows a `⚠Auth conflict` warning when it starts, the agent should still work through JetBrains Central CLI as long as `apiKeyHelper` is configured.
:
:
:
: To make the warning disappear, make sure neither `ANTHROPIC_API_KEY` nor `ANTHROPIC_AUTH_TOKEN` is set in your shell environment or shell startup files.
:
:
:
: In the current shell session, you can clear them with:
:
:
:
:
:
:
: ```BASH
: unset ANTHROPIC_API_KEY ANTHROPIC_AUTH_TOKEN
: ```

Gemini CLI:

auth picker / "GOOGLE_CLOUD_PROJECT should be set"
: Gemini CLI requires workspace trust. When you open Gemini CLI in a new folder, it asks whether to trust the workspace. If you decline, Gemini CLI ignores `settings.json` and `.env`. Then JetBrains Central CLI configuration is not applied. Trust the folder when prompted, or type `/permissions` inside Gemini CLI to change trust settings.

Agent not working after wiring
: Try the following:
:
:
:
: 1.  Check proxy is running: `central status`
:
: 2.  Open a new terminal and run the agent again.
:
: 3.  Verify the config. Check the agent's config file to ensure the base URL points to the proxy.

"Connection refused" errors
: Proxy isn't running. Start it with:
:
:
:
:
:
:
: ```BASH
: central proxy start
: ```

"Unauthorized" or "Forbidden" errors
: Your token may have expired. JetBrains Central CLI auto-refreshes tokens, but if it fails:
:
:
:
: 1.  Run `central logout`
:
: 2.  Run `central login`

Agent shows "wired" but requests fail
: Verify the config file has the correct URL:
:
:
:
: Claude Agent:
:
:
:
: ```BASH
: cat ~/.claude/settings.json
: # Should contain: "ANTHROPIC_BASE_URL": "http://127.0.0.1:{port}/wire/{secret}/claude-code/anthropic"
: ```
:
:
:
: Codex:
:
:
:
: ```BASH
: cat ~/.codex/config.toml
: # Should contain: model_provider = "wire" and base_url with /wire/{secret}/codex/openai
: ```
:
:
:
: Gemini CLI:
:
:
:
: ```BASH
: cat ~/.gemini/.env
: # Should contain: GOOGLE_VERTEX_BASE_URL=http://127.0.0.1:{port}/wire/{secret}/gemini-cli/vertex
: ```

Agent enabled in Central Console is not available
: If an administrator [enables an additional agent](https://www.jetbrains.com.cn/en-us/help/jetbrains-console/ai-policies-configure.html#agents-tab) for you in JetBrains Central Console, the agent may not appear in JetBrains Central CLI immediately.
:
:
:
: Central CLI periodically checks for updated settings, approximately once an hour. So changes made in Central Console may take some time to become available in JetBrains Central CLI.
:
:
:
: To update the settings immediately, run: `central agents refresh`
:
:
:
: Then check the available agents again.
:
:
:
: If the agent is still unavailable, contact your JetBrains Central admin.

## Token issues

Token expired
: Tokens expire roughly every 24 hours. JetBrains Central CLI handles this automatically:
:
:
:
: * The proxy refreshes tokens in the background every 2 hours.
:
: * On 401/403, the proxy refreshes immediately and retries.
:
:
:
: If auto-refresh fails, try logging out and back in with `central logout` and `central login`.

Keychain access denied
: JetBrains Central CLI stores the encryption key in your system keychain.
:
:
:
: macOS:
: Open Keychain Access, search for `wire-jbai`, and allow access.
:
: Linux:
: Make sure `gnome-keyring` or `kwallet` is running. JetBrains Central CLI uses the Secret Service D-Bus API.
:
: Windows:
: Check Credential Manager for the `wire-jbai` entry.

## Report an issue

Procedure: Report an issue from the interactive interface

1. Run `central`.

2. Go to More... | Report issue.

This opens a browser form pre-filled with your version, operating system, proxy status, wired agents, and the last 50 lines of the daemon log.

When contacting JetBrains support manually, gather the following:

macOS / Linux:

```BASH
central --version    # JetBrains Central CLI version
central status       # auth, proxy, and agent status
uname -a             # OS information

# Log files, zipped so you can attach them
zip -rj ~/central-logs.zip ~/.jetbrains-central/logs/
```

Windows:

```POWERSHELL
central --version    # JetBrains Central CLI version
central status       # auth, proxy, and agent status
systeminfo           # OS information

# Log files, zipped so you can attach them
Compress-Archive -Path $HOME\.jetbrains-central\logs\* -DestinationPath $HOME\central-logs.zip -Force
```

Before filing anything, check the sections above — they cover installation, login, proxy, agent, and token problems.