Desktop Troubleshooting
Common issues and solutions for Gauzy desktop applications.
Connection Issuesโ
Cannot connect to APIโ
Symptoms: "Connection failed" or timeout errors.
Solutions:
- Verify API URL in settings matches your server
- Check if the API server is running (
/api/health) - Check firewall rules for the API port
- Ensure SSL certificates are valid (HTTPS)
Offline mode not syncingโ
Solutions:
- Check internet connectivity
- Verify API URL is reachable
- Restart the application
- Check logs for sync errors
Screenshot Issuesโ
Screenshots not capturingโ
Solutions:
- Check employee settings:
isScreenshotEnabled: true - Verify organization allows screenshots
- On Linux/Wayland: install PipeWire and portal (see Wayland Support)
- On macOS: grant Screen Recording permission in System Preferences โ Privacy
Screenshots are black or blankโ
Solutions:
- Update graphics drivers
- Disable hardware acceleration:
--disable-gpu - Check multi-monitor configuration
Installation Issuesโ
Windows: App blocked by SmartScreenโ
The app may not be signed or the certificate is not yet trusted.
Solution: Click "More info" โ "Run anyway" (use official signed builds for production)
macOS: "App is damaged" or cannot be openedโ
Solutions:
# Remove quarantine attribute
xattr -cr /Applications/Gauzy\ Desktop\ Timer.app
# Or allow in System Preferences โ Security & Privacy
Linux: AppImage won't startโ
Solutions:
# Make executable
chmod +x GauzyDesktopTimer.AppImage
# Install FUSE (required for AppImage)
sudo apt install libfuse2
Performance Issuesโ
High memory usageโ
Solutions:
- Reduce screenshot frequency
- Close unnecessary windows
- Update to latest version
- Check for memory leaks in developer tools (
Ctrl+Shift+I)
High CPU usageโ
Solutions:
- Disable activity tracking if not needed
- Reduce screenshot resolution
- Update Electron to latest version
Loggingโ
View logsโ
| Platform | Log Location |
|---|---|
| Windows | %APPDATA%\gauzy-desktop-timer\logs\ |
| macOS | ~/Library/Logs/gauzy-desktop-timer/ |
| Linux | ~/.config/gauzy-desktop-timer/logs/ |
Enable debug loggingโ
# Start with debug logging
DEBUG=* ./GauzyDesktopTimer
Related Pagesโ
- Desktop Overview
- Wayland Support โ Linux Wayland issues
- Desktop Timer โ timer features