Shell App

Troubleshooting

Troubleshooting

This guide covers common issues you may encounter with the Shell App and how to resolve them.

Connection Issues

Issue: "Disconnected" Status Won't Connect

Symptoms:

  • Connection status shows "Disconnected" (gray indicator)
  • Clicking "Connect" doesn't establish connection
  • Auto-reconnect keeps failing

Cause: The shell server may not be running or may be unreachable.

Solution:

  1. Verify the shell server is running

    # For development, start the shell server
yarn dev:shell-server

# Or check if it's running
lsof -i :3001

  2. Check the server URL

    • Go to Settings (/shell/settings)
    • Verify the server URL is correct (default: ws://localhost:3001)
    • For Electron, this is auto-detected

  3. Check network/firewall

    • Ensure port 3001 is not blocked
    • If using a remote server, verify network connectivity

  4. Restart the app

    • Refresh the page (web) or restart the Electron app

Issue: Connection Keeps Dropping

Symptoms:

  • Terminal connects but disconnects frequently
  • "Reconnecting..." appears repeatedly
  • Commands sometimes don't execute

Cause: Network instability or server overload.

Solution:

  1. Check your network connection stability
  2. If on WiFi, try a wired connection
  3. Check server logs for errors:
    yarn docker:logs  # For Docker-based server
  4. Reduce the number of concurrent sessions if many are open

Issue: "Error" Status (Red Indicator)

Symptoms:

  • Connection status shows red "Error"
  • Error message displayed
  • Cannot create or connect to sessions

Cause: Server error, authentication issue, or configuration problem.

Solution:

  1. Check the error message displayed for specific details
  2. Verify authentication - ensure you're logged into FlowState
  3. Check server health:
    # Test WebSocket connection
wscat -c ws://localhost:3001
  4. Clear browser cache and reload
  5. Check browser console (F12) for detailed error logs

Session Issues

Issue: Session Not Appearing in List

Symptoms:

  • Created a session but it doesn't show in sidebar
  • Session list appears empty despite having sessions

Cause: Sync issue between shell server and RxDB, or session may be associated with different workspace.

Solution:

  1. Refresh the session list - disconnect and reconnect to the server
  2. Check workspace context - ensure you're viewing the correct workspace
  3. Verify RxDB sync:
    • Open browser DevTools
    • Check Network tab for RxDB replication requests
  4. Manually list sessions from server:
    • The app should automatically list sessions on connect
    • If not, the server may need restart

Issue: Cannot Reconnect to Existing Session

Symptoms:

  • Clicking on a session in the list doesn't open terminal
  • Session shows but terminal area is blank
  • "Session not found" error

Cause: The shell process for that session may have exited on the server.

Solution:

  1. Delete and recreate - if the session process exited, delete the old session and create a new one
  2. Check session status - closed sessions (process exited) can't be reconnected
  3. Verify server has the session:
    • Sessions are tracked by the shell server
    • Server restart clears active sessions

Issue: Session History Not Restored

Symptoms:

  • Reconnected to session but previous output is gone
  • Terminal starts fresh despite having history

Cause: History scrollback depends on server-side buffer retention.

Solution:

  1. Understand history limits - the shell server maintains a limited scrollback buffer
  2. Use terminal scrollback - scroll up in the terminal to see available history
  3. For persistent logs - redirect command output to files:
    ./script.sh | tee output.log

Terminal Issues

Issue: Terminal Display Corrupted

Symptoms:

  • Characters appear in wrong positions
  • Colors are wrong or missing
  • Cursor position incorrect

Cause: Terminal dimension mismatch or encoding issues.

Solution:

  1. Reset terminal:
    reset
# or
clear
  2. Resize the terminal - drag the divider or resize the window
  3. Check TERM variable:
    echo $TERM  # Should be xterm-256color or similar

Issue: Special Characters Not Working

Symptoms:

  • Backspace doesn't delete characters
  • Arrow keys print escape sequences instead of navigating
  • Tab completion doesn't work

Cause: Terminal type not properly set or input handling issue.

Solution:

  1. Set terminal type:
    export TERM=xterm-256color
  2. Check shell - some shells handle input differently:
    echo $SHELL  # Verify you're using bash/zsh
  3. Try different browser - some browsers handle key events differently

Issue: Copy/Paste Not Working

Symptoms:

  • Cannot paste text into terminal
  • Cannot copy text from terminal output

Cause: Browser clipboard permissions or keyboard shortcut conflicts.

Solution:

  1. Use correct shortcuts:
    • Copy: Ctrl+Shift+C (Linux), Cmd+C (macOS), or right-click
    • Paste: Ctrl+Shift+V (Linux), Cmd+V (macOS), or right-click
  2. Grant clipboard permissions when prompted by browser
  3. Right-click context menu - use the terminal's context menu if shortcuts fail

Performance Issues

Issue: Terminal Feels Slow/Laggy

Symptoms:

  • Typing has noticeable delay
  • Command output appears slowly
  • Scrolling is choppy

Cause: Network latency, large output volume, or browser performance.

Solution:

  1. Check network latency to the shell server
  2. Reduce output volume:
    # Instead of cat large-file.txt
head -100 large-file.txt

# Or use pagination
less large-file.txt
  3. Clear terminal buffer periodically (Ctrl+K or Cmd+K)
  4. Close unused sessions to reduce memory usage
  5. Check browser performance:
    • Close unnecessary tabs
    • Disable browser extensions temporarily

Issue: High Memory Usage

Symptoms:

  • Browser becomes sluggish
  • System memory usage high when using Shell App
  • Page eventually crashes

Cause: Too many sessions or excessive terminal output.

Solution:

  1. Close unused sessions - delete sessions you're not actively using
  2. Clear terminal output regularly
  3. Limit long-running commands that produce continuous output
  4. Restart the app periodically during heavy use

Getting Help

If you can't resolve your issue using this guide:

  1. Check the FAQ for additional answers
  2. Review Features to ensure you're using the app correctly
  3. Gather diagnostic information:
    • Browser console logs (F12 > Console)
    • Network requests (F12 > Network)
    • Shell server logs
    • Exact error messages
  4. Contact support with:
    • Description of the issue
    • Steps to reproduce
    • Screenshots or recordings if applicable
    • Browser and OS version
    • FlowState version (check About page at /shell/about)
Previous
Running Commands
Next
FAQ