Troubleshooting

Common issues and their solutions.

Diagnostics first

When running the desktop application, the easiest way to diagnose issues is by checking the logs and Developer Tools:

  • Open Developer Tools: In the application window, go to the top menu bar and select View → Toggle Developer Tools. The Console tab shows any React or connection errors.
  • Check app logs: Frontend and backend logs are written to files inside your user app data directory (e.g. ~/.asyncat/logs/backend.log or the Electron process output).

Startup issues

App opens but shows a loading screen forever

This happens when Electron cannot connect to the backend server (port 8716). Check if another process is occupying the port:

# macOS / Linux
lsof -ti :8716 | xargs kill

# Windows (PowerShell)
Stop-Process -Id (Get-NetTCPConnection -LocalPort 8716).OwningProcess

If running from source, verify that your den/.env exists and is configured correctly.

better-sqlite3 crashes or fails to load

For source installations, the native SQLite binary must match Electron's Node version ABI. Run the rebuild command:

npm run electron:rebuild

Always run this after installing new dependencies or changing Node versions.

Tray icon missing on Linux

Linux distributions using GNOME or other desktops may require AppIndicator libraries to draw system tray icons:

sudo apt install libappindicator1
# or
sudo apt install libayatana-appindicator1

Agent issues

Agent not responding

  1. Check your AI provider is configured — go to Settings → Models → Chat Provider.
  2. Verify the API key is valid and the endpoint is reachable: curl <your-ai-base-url>/models
  3. Check that JWT_SECRET is configured in den/.env (for source runs) or generated inside the app settings.
  4. Open developer tools (View → Toggle Developer Tools) and check for connection errors to port 8716.

Agent gets stuck in a loop

asyncat has built-in loop detection — a sliding window of 8 normalized tool signatures triggers a strategy switch automatically. If an agent run genuinely hangs, stop it in the UI and try a more specific goal or switch to plan mode first to review the approach.

Permission prompt keeps appearing

The permission system requires approval for moderate and dangerous tools. To auto-approve moderate-risk tools for a session, set the auto-approve level in Settings → Agent → Permissions. dangerous tools always require explicit approval.

Local models

llama-server won't start

Verify that your hardware configuration matches the requirements. Common fixes:

  • Ensure the llama.cpp server is installed: Go to Models → Local Engine and trigger a managed installation.
  • Ensure your system Python env doesn't conflict. Asyncat uses its own virtual environment fallback on Linux and macOS to avoid system conflicts.

Local model is very slow

CPU inference is significantly slower than GPU. Make sure asyncat is using your GPU:

  • Go to Models → Local Engine and check the detected hardware. asyncat auto-detects CUDA, Apple Metal, and ROCm.
  • For llama.cpp: ensure the binary was compiled with your GPU backend. The --n-gpu-layers 99 flag offloads all layers to GPU.
  • Model must fit in VRAM. A 7B Q4 model needs ~4GB; a 13B Q4 needs ~8GB.

Ollama not connecting

Make sure Ollama is running (ollama serve) and set the provider URL to http://localhost:11434/v1 in Settings.

Integrations

MCP server not connecting

Check the registered command is correct and runnable. You can view, disable, or delete MCP configurations directly in the UI under Settings → MCP Servers, or inspect the raw configuration file at data/mcp.json inside the application workspace.

GitHub / Google Calendar OAuth not working

OAuth integrations require the backend to be reachable at a stable URL for the OAuth callback. On localhost this works out of the box. On a server, set BACKEND_URL in den/.env to your public URL.