Troubleshooting

This guide covers common issues users encounter with the Launcher App and their solutions.

Common Issues

Issue: App Cards Not Displaying

Symptoms:

• The Launcher shows an empty grid
• Only some apps appear in the launcher
• App icons show as generic boxes

Cause: Apps may not be properly registered in the app manifest, or there's an issue loading the manifest data.

Solution:

1. Refresh the page (Ctrl/Cmd + R)
2. Verify that apps have valid flowstate.json manifest files
3. Check the browser console for manifest loading errors
4. Ensure all app packages are properly built

# Rebuild all app packages
yarn build

Issue: Status Bar Shows Incorrect Information

Symptoms:

• Mode shows "undefined" or incorrect value
• Server count doesn't match actual servers
• Organization name is missing

Cause: The server configuration context may not be properly initialized.

Solution:

1. Ensure the RxDB server is running
2. Check your network connection
3. Refresh the page to reinitialize contexts
4. Verify organization settings in the selector

# Start the RxDB server
yarn docker:start

Issue: Clicking an App Card Does Nothing

Symptoms:

• App cards don't respond to clicks
• Navigation doesn't occur after clicking
• Console shows routing errors

Cause: The router context may not be available, or the app route is invalid.

Solution:

1. Ensure you're running within a proper router context
2. Check that the target app is properly registered with a valid route
3. Look for JavaScript errors in the browser console
4. Try using keyboard navigation as an alternative

Issue: Organization/Workspace Selector Not Working

Symptoms:

• Selector dropdown doesn't open
• Selection doesn't persist
• Organization list is empty

Cause: Organization data may not be loaded or user permissions are insufficient.

Solution:

1. Verify you're properly authenticated
2. Check that your user has organization access
3. Ensure the database connection is active
4. Clear local storage and refresh

// Clear local storage (run in browser console)
localStorage.clear();
location.reload();

Issue: Keyboard Shortcuts Not Working

Symptoms:

• Cmd/Ctrl+Shift+H doesn't return to launcher
• Other shortcuts are unresponsive
• Shortcuts conflict with browser/system shortcuts

Cause: Keyboard shortcuts may be intercepted by the browser, operating system, or other applications.

Solution:

1. Ensure the FlowState window has focus
2. Check for conflicting shortcuts in browser settings
3. On Electron, shortcuts should work globally; on web, they may be limited
4. Try the alternative: navigate directly to / in the address bar

Issue: App Icons Display as Box Icons

Symptoms:

• Apps show a generic box icon instead of their intended icon
• Icon names in console show as "unknown"

Cause: The Lucide icon specified in the app manifest doesn't exist or is misspelled.

Solution:

1. Check the app's flowstate.json manifest
2. Verify the icon name matches a valid Lucide icon
3. Icon names should use PascalCase (e.g., Rocket, Settings, Folder)

{
  "icon": "Rocket"
}

Issue: Slow Loading or Performance Issues

Symptoms:

• Launcher takes a long time to display
• App grid renders slowly
• Hover effects are laggy

Cause: Too many apps registered, network latency, or browser performance issues.

Solution:

1. Check network connectivity and server response times
2. Disable browser extensions that might interfere
3. Clear browser cache and reload
4. Check system resources (CPU, memory usage)

Platform-Specific Issues

Electron Desktop App

Issue: Window doesn't focus on shortcut

The global shortcut is registered but the window doesn't come to the foreground.

Solution:

1. Check if another application is intercepting the shortcut
2. Restart the Electron app
3. Check the Electron main process logs for errors

Next.js Web App

Issue: Page shows 404 for root route

The launcher doesn't load at the root URL.

Solution:

1. Verify the Next.js routing configuration
2. Check that the Launcher app is properly mounted in the app framework
3. Review the Next.js build output for routing issues

Debug Mode

For advanced troubleshooting, enable debug logging:

// Enable in browser console
localStorage.setItem('flowstate-debug', 'true');
location.reload();

This will output additional information about:

• App manifest loading
• Route resolution
• Context provider initialization
• Framework hook states

Getting Help

If you can't resolve your issue:

1. Check the FAQ for additional answers
2. Review the Features documentation for expected behavior
3. Search existing issues in the repository
4. Contact support with:
   • Description of the issue
   • Steps to reproduce
   • Screenshots if applicable
   • Browser console output
   • Platform (Electron/Next.js) and version information