headquarter/docs/features/terminal-troubleshooting.md

Terminal Troubleshooting Guide

Common Issues

Cannot Connect to Terminal

Symptom: Terminal shows "Connection closed" or "Error" status immediately.

Solutions:

1. Verify the tool instance is running:

   • Check instance status in the UI
   • Start the instance if it's stopped

2. Check browser console for errors:

   • Open browser DevTools (F12)
   • Look for WebSocket connection errors
   • Check for CORS or authentication errors

3. Verify network connectivity:

   • Ensure you can reach the API server
   • Check if WebSocket connections are blocked by firewall/proxy
   • Try accessing from a different network

If the issue persists:

• Reset the terminal session
• Refresh the page
• Check server logs for errors

Terminal Freezes or Becomes Unresponsive

Symptom: Terminal accepts no input or stops updating.

Solutions:

1. Reset the terminal:

   • Click the Reset button in the terminal header
   • Confirm the reset action
   • Wait for the new session to start

2. Check for stuck processes:

   • Try Ctrl+C to interrupt any running process
   • If that doesn't work, reset the terminal

3. Browser issues:

   • Close and reopen the browser tab
   • Clear browser cache and cookies
   • Try a different browser

Output Not Showing

Symptom: Commands execute but no output appears.

Solutions:

1. Check terminal focus:

   • Click inside the terminal area
   • Look for the cursor indicator

2. Resize the terminal:

   • The terminal may need a resize event to render properly
   • Try resizing the browser window slightly

3. Reset the terminal session

Reconnection Loop

Symptom: Terminal keeps disconnecting and reconnecting repeatedly.

Solutions:

1. Check instance health:

   • The instance may be unhealthy or restarting
   • Check instance logs for errors

2. Network stability:

   • Unstable network causes repeated disconnections
   • Try on a more stable connection

3. Multiple tabs:

   • Only one tab can connect to a terminal session
   • Close other tabs with the same terminal open

Diagnostic Steps

Check WebSocket Connection

1. Open browser DevTools (F12)
2. Go to Network tab
3. Filter by "WS" (WebSocket)
4. Look for the terminal WebSocket connection
5. Check:
   • Connection status (should be 101 Switching Protocols)
   • Messages tab for ping/pong traffic
   • Any error messages in the connection

Verify Terminal Session

To check if a terminal session exists on the server:

# Check server logs for session activity
docker logs hq-api | grep -i "terminal"

Look for:

• "Terminal session ready" - session created successfully
• "Reattaching to existing terminal session" - reconnecting to existing session
• "Cleaning up idle terminal session" - session expired

Test Basic Connectivity

# Test if the WebSocket endpoint is reachable
curl -i -N \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket" \
  -H "Sec-WebSocket-Key: test" \
  -H "Sec-WebSocket-Version: 13" \
  https://your-api-domain/ws/tool-instances/test/terminal

Expected: HTTP 400 (invalid instance ID) or redirect to auth

Error Codes

WebSocket Close Codes

• 1000: Normal closure - connection closed cleanly
• 4000: Generic error - check server logs
• 4001: Invalid instance ID - verify the instance exists
• 4003: Unauthorized - session expired or invalid
• 4004: Instance not running - start the instance first

HTTP Status Codes

• 404: Instance not found - verify instance ID
• 400: Instance not running - start the instance
• 500: Server error - check server logs

Resetting Everything

If all else fails:

1. Reset terminal session:

   POST /api/projects/{project_id}/repositories/{repo_id}/instances/{instance_id}/terminal/reset
   

2. Restart the tool instance:

   • Stop the instance
   • Start the instance again
   • Reconnect to the terminal

3. Clear browser data:

   • Clear cookies for the domain
   • Clear local storage
   • Hard refresh the page (Ctrl+F5)

Getting Help

If issues persist:

1. Collect diagnostic information:

   • Browser console logs
   • Network tab WebSocket messages
   • Server logs (docker logs hq-api)
   • Instance status and health

2. Check the Terminal API documentation for protocol details

3. Report issues with:

   • Steps to reproduce
   • Expected vs actual behavior
   • Browser and OS version
   • Instance type and configuration