Troubleshooting
Common issues and how to resolve them.
To debug issues with quantumcoderxyz, start by checking the logs and local data it stores on disk.
Logs
CLI and server logs are written to:
- macOS/Linux:
~/.local/share/quantumcoderxyz/log/quantumcoderxyz.log - Windows: Press
WIN+Rand paste%USERPROFILE%\.local\share\quantumcoderxyz\log
Logs are appended to quantumcoderxyz.log. Run quantumcoderxyz debug paths to find the log directory if you use custom XDG paths.
You can set the log level with the --log-level command-line option to get more detailed debug information. For example, quantumcoderxyz --log-level DEBUG.
Storage
quantumcoderxyz stores session data and other application data on disk at:
- macOS/Linux:
~/.local/share/quantumcoderxyz/ - Windows: Press
WIN+Rand paste%USERPROFILE%\.local\share\quantumcoderxyz
This directory contains:
auth.json- Authentication data like API keys, OAuth tokenslog/- Application logsquantumcoderxyz.db- SQLite database containing projects, sessions, and messagessnapshot/- Project snapshots used for undo
Run quantumcoderxyz db path to find the active database. Custom quantumcoderxyz_DB settings and development channels can use a different filename.
Uninstall
To uninstall the quantumcoderxyz CLI and remove its related files, run:
quantumcoderxyz uninstallThe command shows what will be removed and asks for confirmation. See the CLI reference for options to keep your configuration or application data.
To remove quantumcoderxyz Desktop, uninstall the application through your operating system’s app management tools.
Desktop app
quantumcoderxyz Desktop uses Electron and runs a local quantumcoderxyz server in the background. Most issues are caused by a misbehaving plugin, a corrupted cache, or a bad server setting.
Desktop logs are stored in timestamped directories under logs/ in the desktop app data directory.
Quick checks
- Fully quit and relaunch the app.
- If the app shows an error screen, click Restart and copy the error details.
- macOS only:
quantumcoderxyzmenu -> Reload Webview (helps if the UI is blank/frozen).
Disable plugins
If the desktop app is crashing on launch, hanging, or behaving strangely, start by disabling plugins.
Check the global config
Open your global config file and look for a plugin key.
- macOS/Linux:
~/.config/quantumcoderxyz/quantumcoderxyz.jsonc(or~/.config/quantumcoderxyz/quantumcoderxyz.json) - macOS/Linux (older installs):
~/.local/share/quantumcoderxyz/quantumcoderxyz.jsonc - Windows: Press
WIN+Rand paste%USERPROFILE%\.config\quantumcoderxyz\quantumcoderxyz.jsonc
If you have plugins configured, temporarily disable them by removing the key or setting it to an empty array:
{ "$schema": "https://api.quantumcoder.xyz/config.json", "plugin": [],}Check plugin directories
quantumcoderxyz can also load local plugins from disk. Temporarily move these out of the way (or rename the folder) and restart the desktop app:
- Global plugins
- macOS/Linux:
~/.config/quantumcoderxyz/plugins/ - Windows: Press
WIN+Rand paste%USERPROFILE%\.config\quantumcoderxyz\plugins
- macOS/Linux:
- Project plugins (only if you use per-project config)
<your-project>/.quantumcoderxyz/plugins/
If the app starts working again, re-enable plugins one at a time to find which one is causing the issue.
Clear the cache
If disabling plugins doesn’t help (or a plugin install is stuck), clear the cache so quantumcoderxyz can rebuild it.
- Quit quantumcoderxyz Desktop completely.
- Delete the cache directory:
- macOS: Finder ->
Cmd+Shift+G-> paste~/.cache/quantumcoderxyz - Linux: delete
~/.cache/quantumcoderxyz(or runrm -rf ~/.cache/quantumcoderxyz) - Windows: Press
WIN+Rand paste%USERPROFILE%\.cache\quantumcoderxyz
- Restart quantumcoderxyz Desktop.
Fix server connection issues
quantumcoderxyz Desktop can either start its own local server (default) or connect to a server URL you configured.
If you see a “Connection Failed” dialog (or the app never gets past the splash screen), check for a custom server URL.
Clear the desktop default server URL
From the Home screen, click the server name (with the status dot) to open the Server picker. In the Default server section, click Clear.
Remove server.port / server.hostname from your config
If your quantumcoderxyz.json(c) contains a server section, temporarily remove it and restart the desktop app.
Check environment variables
If you have quantumcoderxyz_PORT set in your environment, the desktop app will try to use that port for the local server.
- Unset
quantumcoderxyz_PORT(or pick a free port) and restart.
Linux: Wayland / X11 issues
On Linux, some Wayland setups can cause blank windows or compositor errors.
- Try launching under an X11 session to check whether the issue is specific to Wayland.
Windows: General performance issues
If you’re experiencing slow performance, file access issues, or terminal problems on Windows, try using WSL (Windows Subsystem for Linux). WSL provides a Linux environment that works more seamlessly with quantumcoderxyz’s features.
Notifications not showing
quantumcoderxyz Desktop only shows system notifications when:
- notifications are enabled for quantumcoderxyz in your OS settings, and
- the app window is not focused.
Reset desktop app storage (last resort)
If the app won’t start and you can’t clear settings from inside the UI, reset the desktop app’s saved state.
- Quit quantumcoderxyz Desktop.
- Find and delete these files (they live in the quantumcoderxyz Desktop app data directory):
quantumcoderxyz.settings(desktop settings, including the default server URL)quantumcoderxyz.global.datandquantumcoderxyz.workspace.*.dat(UI state like recent servers/projects)
For the stable release, the desktop app data directory is:
- macOS:
~/Library/Application Support/ai.quantumcoderxyz.desktop/ - Linux:
~/.config/ai.quantumcoderxyz.desktop/(or$XDG_CONFIG_HOME/ai.quantumcoderxyz.desktop/) - Windows:
%APPDATA%\ai.quantumcoderxyz.desktop\
Beta and development builds use the ai.quantumcoderxyz.desktop.beta and ai.quantumcoderxyz.desktop.dev directories instead.
Getting help
If you’re experiencing issues with quantumcoderxyz:
-
Report issues on GitHub
The best way to report bugs or request features is through our GitHub repository:
github.com/anomalyco/quantumcoderxyz/issues
Before creating a new issue, search existing issues to see if your problem has already been reported.
-
Join our Discord
For real-time help and community discussion, join our Discord server:
Common issues
Here are some common issues and how to resolve them.
quantumcoderxyz won’t start
- Check the logs for error messages
- Try running with
--print-logsto see output in the terminal - Ensure you have the latest version with
quantumcoderxyz upgrade
Authentication issues
- Try re-authenticating with the
/connectcommand in the TUI - Check that your API keys are valid
- Ensure your network allows connections to the provider’s API
Model not available
- Check that you’ve authenticated with the provider
- Verify the model name in your config is correct
- Some models may require specific access or subscriptions
If you encounter ProviderModelNotFoundError you are most likely incorrectly
referencing a model somewhere.
Models should be referenced like so: <providerId>/<modelId>
Examples:
openai/gpt-6.1-solopenrouter/google/gemini-3.8-flashquantumcoderxyz/kimi-k2
To figure out what models you have access to, run quantumcoderxyz models
ProviderInitError
If you encounter a ProviderInitError, you likely have an invalid or corrupted configuration.
To resolve this:
-
First, verify your provider is set up correctly by following the providers guide
-
If the issue persists, try clearing your stored configuration:
Terminal window rm -rf ~/.local/share/quantumcoderxyzOn Windows, press
WIN+Rand delete:%USERPROFILE%\.local\share\quantumcoderxyz -
Re-authenticate with your provider using the
/connectcommand in the TUI.
AI_APICallError and provider package issues
If you encounter API call errors, this may be due to outdated provider packages. quantumcoderxyz dynamically installs provider packages (OpenAI, Anthropic, Google, etc.) as needed and caches them locally.
To resolve provider package issues:
-
Clear the provider package cache:
Terminal window rm -rf ~/.cache/quantumcoderxyzOn Windows, press
WIN+Rand delete:%USERPROFILE%\.cache\quantumcoderxyz -
Restart quantumcoderxyz to reinstall the latest provider packages
This will force quantumcoderxyz to download the most recent versions of provider packages, which often resolves compatibility issues with model parameters and API changes.
Copy/paste not working on Linux
Linux users need to have one of the following clipboard utilities installed for copy/paste functionality to work:
For X11 systems:
apt install -y xclip# orapt install -y xselFor Wayland systems:
apt install -y wl-clipboardFor headless environments:
apt install -y xvfb# and run:Xvfb :99 -screen 0 1024x768x24 > /dev/null 2>&1 &export DISPLAY=:99.0quantumcoderxyz will detect if you’re using Wayland and prefer wl-clipboard, otherwise it will try to find clipboard tools in order of: xclip and xsel.