Common Issues

Common Issues

Device Shows as "Offline"

Problem: Your device appears as offline in the Sulala dashboard even though the agent is running.

Solutions:

1. Check agent is running
   • Verify the agent process is active
   • Check for error messages in the console/logs
2. Verify API key
   • Ensure the API key matches the device in the dashboard
   • Get the correct API key from Dashboard → Devices → Your Device → API Key
3. Check server URL
   • Verify the server URL is correct
   • For local development: http://localhost:3000
   • For production: https://sulala.ai or your custom domain
4. Check internet connection
   • Ensure your device has internet access
   • Test connectivity to the server URL
5. Restart the agent
   • Stop and restart the device agent
   • Wait 30-60 seconds for the heartbeat to register

"Invalid API key" Error

Problem: The agent reports an invalid API key error.

Solutions:

1. Verify API key format
   • API keys should start with sul_
   • Check for typos or extra spaces
2. Get fresh API key
   • Go to Dashboard → Devices → Your Device → API Key
   • Copy the key again (it may have been regenerated)
3. Check key permissions
   • Ensure the API key is for the correct device
   • Verify the device exists in the dashboard

Connection Timeout

Problem: The agent cannot connect to the server.

Solutions:

1. Check server is running
   • Verify the Sulala server is running
   • Test the server URL in a browser
2. Check firewall settings
   • Ensure firewall allows outbound connections
   • Check if corporate firewall is blocking requests
3. Verify server URL
   • Test the URL: curl http://localhost:3000/api/health (or your server URL)
   • Ensure the URL is accessible from your network
4. Check network configuration
   • For local development, ensure you're using localhost or 127.0.0.1
   • For remote servers, ensure the URL is correct

Search Not Finding Files

Problem: Searches return no results even though files exist.

Solutions:

1. Check search scope
   • File search is limited to user directories for performance
   • App search is limited to standard installation locations
2. Verify file permissions
   • Ensure the agent has read permissions for the directories
   • Check file system permissions
3. Check search paths
   • macOS: Searches /Applications and ~/Applications
   • Windows: Searches Program Files directories
   • Linux: Searches /usr/bin, /usr/local/bin, /opt
4. File indexing delay
   • Some files may take time to be indexed
   • Try searching again after a few minutes

Agent Crashes or Stops Running

Problem: The agent stops working unexpectedly.

Solutions:

1. Check logs
   • Review console output for error messages
   • Check system logs for crashes
2. Update dependencies
   • For JavaScript agent: npm install to update packages
   • For Flutter agent: flutter pub get to update dependencies
3. Check system resources
   • Ensure sufficient memory and disk space
   • Close other resource-intensive applications
4. Restart the agent
   • Stop the agent completely
   • Restart it and monitor for errors

System Tray Not Working

Problem: System tray icon doesn't appear or doesn't work.

Solutions:

1. Platform support
   • System tray is optional and may not work on all platforms
   • The app will continue to function without tray support
2. Keep window open
   • You can keep the main window open instead
   • Minimize to taskbar/dock if needed
3. Check platform-specific requirements
   • macOS: May require proper app signing
   • Windows: Should work by default
   • Linux: May vary by desktop environment

Build Errors

Problem: Unable to build the agent for distribution.

Solutions:

JavaScript Agent

1. Check Node.js version

   node --version  # Should be 18+
   

2. Clean and reinstall

   rm -rf node_modules package-lock.json
   npm install
   

3. Check Electron version
   • Ensure Electron is properly installed
   • Try updating Electron: npm update electron

Flutter Agent

1. Run Flutter doctor

   flutter doctor
   

   
   Fix any issues reported
2. Clean build

   flutter clean
   flutter pub get
   

3. Check platform requirements
   • macOS: Xcode and CocoaPods
   • Windows: Visual Studio with C++ tools
   • Linux: GTK development libraries
   • Android: Android SDK
   • iOS: Xcode (macOS only)

File Upload Fails

Problem: File uploads to cloud storage fail.

Solutions:

1. Check file size
   • Ensure file is within size limits
   • Large files may timeout
2. Verify permissions
   • Ensure the agent has read access to the file
   • Check file is not locked by another process
3. Check network
   • Verify internet connection is stable
   • Check if upload endpoint is accessible
4. Review error messages
   • Check console/logs for specific error details
   • May indicate server-side issues

Getting Help

If you're still experiencing issues:

1. Check the logs
   • Review agent console output
   • Check system logs
2. Verify configuration
   • Double-check API key and server URL
   • Ensure all prerequisites are met
3. Test connectivity
   • Test server URL in browser
   • Verify network connectivity
4. Contact support
   • Provide error messages and logs
   • Include your platform and agent version

Platform-Specific Issues

macOS

• Code signing: May see warnings if building without signing
• File permissions: May need to grant Full Disk Access
• System tray: Requires proper app bundle structure

Windows

• Antivirus: May flag the agent, add exception if needed
• Firewall: May need to allow the app through firewall
• Permissions: May need to run as administrator for some operations

Linux

• Desktop environment: System tray behavior varies
• Permissions: May need to adjust file permissions
• Dependencies: Ensure all required libraries are installed

Mobile (Flutter)

• Permissions: Request proper permissions for file access
• Background: May need to configure background execution
• Battery optimization: Disable battery optimization for reliable operation