Skip to main content

​
Connection Issues

​
WebSocket fails to connect

Chat doesn’t work, “Connection error” message appears
  1. Check agent backend is running: curl http://localhost:3001/health
  2. Verify WebSocket URL in environment
  3. Check CORS settings if cross-origin

​
Authentication fails

“Unauthorized” error, redirected to login
  1. Clear local storage and re-login
  2. Check JWT expiration
  3. Verify JWT_SECRET matches between services

​
Agent Issues

​
Agent not responding

Messages sent but no response
  1. Check Anthropic API key is valid
  2. Verify API rate limits not exceeded
  3. Check agent backend logs

​
Tools not working

“Tool not found” or execution errors
  1. Verify tool is registered
  2. Check permission mode allows the tool
  3. Review tool handler for errors

​
Desktop Issues

​
App won’t start

App crashes on launch
  1. Clear app data: ~/Library/Application Support/OMNI
  2. Reinstall the application
  3. Check crash logs in app data folder

​
Auto-update fails

Update notification but update fails
  1. Check internet connection
  2. Verify code signing is valid
  3. Manual download from GitHub releases

​
Build Issues

​
TypeScript errors

  1. Run pnpm typecheck to see all errors
  2. Ensure all dependencies installed
  3. Check for version mismatches

​
Docker build fails

  1. Ensure Docker daemon is running
  2. Clear Docker cache: docker builder prune
  3. Check Dockerfile syntax

​
Getting Help

If these solutions don’t work:

GitHub Issues

Search existing issues

Discord

Ask the community

Email Support

Contact support
When creating a new issue, include:
  • Steps to reproduce
  • Error messages
  • Environment details