Troubleshooting

CoDev Desktop runs a local CoDev Code server in the background. Most problems are a misbehaving plugin, a stale cache, or a server setting pointing somewhere it should not.

For problems that are not specific to the desktop app — models, providers, authentication, logs — see Troubleshooting in the CoDev Code docs.

Quick checks

• Fully quit and relaunch the app.
• If the app shows an error screen, click Restart and copy the error details.
• macOS only: CoDev menu → Reload Webview, which helps if the UI is blank or frozen.

Collecting a debug log

Use the debug log export in the app. It writes a codev-debug-<timestamp>.zip file to your Downloads folder — attach it to a bug report.

Renderer log lines carry their structured data rather than reaching the bundle as [object Object], so the export reflects what the app actually reported. A connection blip while a server restarts (a sandbox reset, the app relaunching its server) is not logged as an error; only a connection that keeps failing is.

Disable plugins

If the app is crashing on launch, hanging, or behaving strangely, start by disabling plugins.

Check the global config. Open it and look for a plugin key:

• macOS/Linux: ~/.config/codev/codev.jsonc (or ~/.config/codev/codev.json)
• macOS/Linux (older installs): ~/.local/share/codev/codev.jsonc
• Windows: press WIN+R and paste %USERPROFILE%\.config\codev\codev.jsonc

If you have plugins configured, temporarily disable them by removing the key or setting it to an empty array:

{
  "plugin": [],
}

Check plugin directories. CoDev can also load local plugins from disk. Temporarily move these out of the way (or rename the folder) and restart the app:

• Global plugins — ~/.config/codev/plugins/ on macOS and Linux; %USERPROFILE%\.config\codev\plugins on Windows
• Project plugins — <your-project>/.codev/plugins/, only if you use per-project config

If the app starts working again, re-enable plugins one at a time to find the one at fault.

Clear the cache

If disabling plugins does not help, or a plugin install is stuck, clear the cache so CoDev can rebuild it.

Server connections

The app either starts its own local server (the default) or connects to a server URL you configured. If you see a Connection Failed dialog, or never get 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. Under Default server, click Clear.

Remove server.port / server.hostname from your config. If your codev.json(c) has a server section, take it out temporarily and restart.

Check environment variables. With CODEV_PORT set, the app tries to use that port for the local server. Unset it, or pick a free one, and restart.

Could not reach Local Server, on a corporate network. This is handled — the app waits out the network's proxy configuration instead of declaring the server down. If you still see it, the server really did fail to start; the debug log export says why.

macOS: "Apple could not verify" on first launch

The macOS builds are not yet signed with an Apple Developer ID, so Gatekeeper blocks the first launch and offers only Move to Trash and Done.

Allow it once in System Settings → Privacy & Security, where an Open Anyway button appears after the blocked launch, or clear the quarantine flag from the Terminal:

xattr -dr com.apple.quarantine /Applications/CoDev.app

Linux: Wayland / X11

Some Wayland setups cause blank windows or compositor errors.

• On Wayland with a blank or crashing window, try launching with OC_ALLOW_WAYLAND=1.
• If that makes it worse, remove it and try an X11 session instead.

Windows: WebView2 runtime

CoDev Desktop needs the Microsoft Edge WebView2 Runtime on Windows. If the app opens to a blank window or will not start, install or update WebView2 and try again.

Windows: general performance

For slow performance, file access issues or terminal problems on Windows, run CoDev inside WSL — a Linux environment fits CoDev's file operations more closely than Windows does.

Sandboxes

"Your sandbox is not running yet" while it is being created or started is normal — it clears itself when the sandbox is ready.

A sandbox that failed to start says so in the Work sidebar, with the failure message and a retry in place.

nft is missing from the guest image — the sandbox is on an image older than the app requires. Use its Reset button.

Model calls failing with Cannot connect to API: other side closed on Windows means the guest cannot reach the host relay. The app tries the shared loopback that WSL's mirrored networking provides and the NAT gateway, and turns the connection around over its own localhost channel when a managed firewall drops both — so if you still see it, collect a debug log.

exited 4294967295 from wsl --import means WSL was installed but Windows has not been restarted yet. Restart and try again.

A sandbox that will not start after a force quit clears its own leftover state on the next start. If it persists, Reset the sandbox.

See Sandboxes for the rest.

Notifications not showing

The app only shows system notifications when notifications are enabled for CoDev in your OS settings and the app window is not focused.

Reset the app's stored state (last resort)

If the app will not start and you cannot clear settings from inside the UI, reset its saved state.

This does not touch your sessions, config or credentials — those live outside the desktop app's directory.