# 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:

```bash
# 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

```bash
# 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](/docs/api/terminal.md) for protocol details

3. Report issues with:
   - Steps to reproduce
   - Expected vs actual behavior
   - Browser and OS version
   - Instance type and configuration