Desktop Troubleshooting

App Won't Launch

App doesn't open after clicking the icon

macOS:

1. Check if the app is blocked by Gatekeeper: Go to System Settings → Privacy & Security and look for a message about Cosmo being blocked. Click Open Anyway.
2. Try launching from the terminal to see error output:

   open -a Cosmo

3. Check Console.app for crash logs related to Cosmo

Windows:

1. Right-click the icon and select Run as administrator to rule out permission issues
2. Check the Windows Event Viewer (Application logs) for crash details
3. Ensure your antivirus isn't blocking the app

App crashes immediately on launch

Try clearing the app cache:

macOS:

rm -rf ~/Library/Application\ Support/Cosmo/Cache
rm -rf ~/Library/Caches/com.getcosmo.cosmo

Windows:

%APPDATA%\Cosmo\Cache

Delete the Cache folder, then relaunch.

If it still crashes, reinstall the app:

1. Uninstall Cosmo (macOS: drag to Trash; Windows: Add/Remove Programs)
2. Download the latest version from cosmo.dev/download
3. Install fresh

Your cloud data (workspaces, artifacts, memory) is unaffected — it's stored in Cosmo's cloud, not locally.

"App is damaged and can't be opened" (macOS)

This is a macOS security warning for apps not from the App Store. Fix it by removing the quarantine attribute:

xattr -cr /Applications/Cosmo.app

Then try launching again.

Blank Screen / White Screen

App launches but shows a blank white screen

This is usually a GPU rendering issue (common on certain graphics configurations).

Fix 1: Disable hardware acceleration

On macOS, launch with:

open -a Cosmo --args --disable-gpu

On Windows, create a shortcut with the flag:

"C:\Program Files\Cosmo\Cosmo.exe" --disable-gpu

Fix 2: Clear renderer cache

macOS:

rm -rf ~/Library/Application\ Support/Cosmo/Cache

Windows:

%APPDATA%\Cosmo\Cache

Fix 3: Check for GPU driver updates

Outdated GPU drivers can cause rendering issues. Update your GPU drivers to the latest version from the manufacturer's website.

Screen flickers or has rendering artifacts

This is also typically a GPU issue. Try disabling hardware acceleration (see above). If you're on an external display or switching between display configurations, disconnect and reconnect your external monitors.

Sign In Issues

Can't sign in — browser doesn't open

The desktop app opens your browser to complete authentication. If nothing opens:

1. Check that you have a default browser set
2. Try manually opening cosmo.dev/auth/desktop
3. On Windows, ensure no browser is set to "Always ask" for protocol handling

Signed in on browser but app still shows login screen

The app waits for a deep link callback from the browser. If the deep link doesn't fire:

1. Check that your browser allows cosmo:// deep links
2. On macOS: Go to System Settings → Privacy & Security → Full Disk Access — ensure no restrictions block the deep link
3. Try right-clicking the desktop app icon → Open to bypass Gatekeeper, which can interfere with deep links
4. As a fallback, use the Sign in with token option in the app and generate a token from Settings → API Keys in the web app

"Session expired" keeps appearing

Re-authenticate:

1. Click your profile in the sidebar
2. Select Sign out
3. Sign back in

If this keeps happening frequently, check that your system clock is accurate — auth tokens are time-sensitive. On macOS, go to System Settings → General → Date & Time and enable Set time and date automatically.

Performance Issues

App is slow or unresponsive

Check memory usage: The app uses Electron (Chromium + Node.js) and can consume significant RAM with many open sessions.

1. Close sessions you're not actively using
2. Restart the app to free memory
3. If you have <8GB RAM, performance may be limited

Disable hardware acceleration (can help on some systems): Go to Settings → Advanced → Disable hardware acceleration and restart.

Chat responses are slow

Slow AI responses are almost always network or provider-side, not the app itself.

1. Check your internet connection speed
2. Visit status.getcosmo.app for active incidents
3. Try switching to a different AI model — some models respond faster than others (e.g., Claude 3 Haiku vs. Claude 3 Opus)
4. Reduce context: very long conversations carry more context each turn, which slows responses

Streaming text stutters or stops mid-response

1. Check your internet connection — streaming responses are sensitive to connection instability
2. If the response fully stops, click Stop and try again
3. Check if the issue is model-specific by switching models

App Updates

Update available but won't install

1. Click the update notification in the sidebar
2. Wait for the download to complete (progress shown in the notification)
3. Click Restart to update

If the update fails:

1. Download the latest version manually from cosmo.dev/download
2. Install it on top of the existing installation — no uninstall needed

App keeps prompting to update but I'm on the latest version

Go to Settings → About to see your current version and the latest available version. If they match, dismiss the notification. If there's a mismatch, force a check:

1. Quit and relaunch the app
2. The update check runs automatically on launch

Data & Sync Issues

Workspaces or artifacts are missing

Workspace data is stored in Cosmo's cloud. If data appears missing:

1. Check your internet connection — data loads from the cloud on startup
2. Ensure you're signed into the correct organization (check the org name in the sidebar)
3. Pull latest data: Go to Settings → Sync → Force sync
4. Check if you're in a different workspace than expected

Changes aren't syncing to other devices

1. Ensure cloud sync is enabled (Settings → Sync — requires Standard plan or above)
2. Check your internet connection on both devices
3. Force a sync on both devices

"Failed to sync" error

1. Check your internet connection
2. Check status.getcosmo.app for cloud storage issues
3. Restart the app — sync retries automatically on restart

Integration & Tool Issues

OAuth popup doesn't appear when connecting an integration

The app opens a browser window for OAuth flows. If it doesn't appear:

1. Check that your browser isn't blocking popups from Cosmo's domain
2. Try the integration flow from Settings → Integrations
3. If the popup appears behind other windows, check your taskbar/Dock

See Connection Troubleshooting for more integration-specific issues.

Getting More Help

If your issue isn't covered here:

1. Check the app version: Settings → About
2. Collect logs:
   • macOS: ~/Library/Logs/Cosmo/
   • Windows: %APPDATA%\Cosmo\logs\
3. Contact support@getcosmo.app with:
   • Your OS version
   • App version
   • The exact error message or behavior
   • Relevant log excerpts
   • Steps to reproduce