Troubleshooting

​

WebSocket Connection Issues

​

Connection Closed Error

// Change from:
const ws = new WebSocket('wss://localhost:8080/ws');

// To:
const ws = new WebSocket('ws://localhost:8080/ws');

​

WebSocket Upgrade Failed

1. Ensure the server is accepting WebSocket connections on the correct port
2. Verify CORS settings allow your origin (controllers/ssh.go:22)
3. Check that the UUID parameter is being passed correctly in the WebSocket URL

Error upgrading to WebSocket: [error details]

• Verify the CheckOrigin function in the WebSocket upgrader is configured correctly
• Ensure your reverse proxy (if any) is configured to pass WebSocket upgrade headers

​

Deployment Issues

​

Database Connection Failed

1. Verify PostgreSQL is running:
   docker ps | grep postgres
   
2. Check database permissions:
   sudo chown -R 1001:1001 ./db/data
   
3. Verify environment variables in docker-compose.yaml:
   environment:
     - DB_HOST=postgres
     - DB_PORT=5432
     - DB_USER=postgres
     - DB_PASSWORD=postgres
     - DB_NAME=sushi
   

​

Port Already in Use

Error starting server: bind: address already in use

1. Find the process using port 8080:
   lsof -i :8080
   
2. Kill the process or change the port in docker-compose.yaml:
   ports:
     - "3000:8080"  # Maps container port 8080 to host port 3000
   

​

Volume Permissions

mkdir -p db/data
sudo chown -R 1001:1001 ./db/data

​

Authentication Errors

​

OAuth Callback Failed

1. Missing OAuth Configuration:
   • Ensure GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are set in docker-compose.yaml
   • Ensure GITHUB_CLIENT_ID and GITHUB_CLIENT_SECRET are set in docker-compose.yaml
2. Incorrect Redirect URL:
   • OAuth redirect URL must match exactly: http://localhost:8080/api/v1/auth/callback
   • Update in your OAuth provider’s console (Google/GitHub)
3. Invalid State Parameter:
   • The state parameter must match between the authorization request and callback
   • Check that state is being properly generated and validated (controllers/oauth.go:60)

​

JWT Token Issues

1. Verify JWT_SECRET is set in environment variables:
   environment:
     - JWT_SECRET=your_secure_secret_here
   
2. Check cookie settings in production:
   • Set HttpOnly: true for security
   • Set Secure: true when using HTTPS
   • Ensure SameSite is configured correctly

​

User Not Found

1. Database connection is active
2. User table exists (run migrations with MIGRATE_DB=true)
3. Username/email is properly stored during OAuth callback

​

SSH Connection Problems

​

Failed to Parse Private Key

1. Invalid Private Key Format:
   • Ensure the private key is in OpenSSH format
   • Check for extra whitespace or line breaks
2. Passphrase Issues:
   • If the key has a passphrase, it must be provided during connection
   • Empty passphrase field when key requires one will cause failure

# OpenSSH format (correct)
-----BEGIN OPENSSH PRIVATE KEY-----
...
-----END OPENSSH PRIVATE KEY-----

# Or RSA format (also supported)
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----

​

Failed to Create Session

Failed to create session: [error details]

1. Verify the SSH connection was established successfully
2. Check that the remote server allows session creation
3. Ensure proper terminal allocation settings (controllers/ssh.go:109)

​

Connection Timeout

1. Verify the hostname and port are correct
2. Ensure the target machine is reachable:
   ping <hostname>
   telnet <hostname> <port>
   
3. Check firewall rules allow SSH connections
4. Verify SSH service is running on the target machine

​

Encryption and Security Issues

​

Decryption Failed

1. Password Mismatch:
   • The decryption password doesn’t match the encryption password
   • Stored in database, used to encrypt/decrypt private keys
2. Corrupted Data:
   • IV (Initialization Vector) or ciphertext was corrupted
   • Database encoding issue

• Algorithm: AES-CFB
• Key derivation: PBKDF2-HMAC-SHA256 (10,000 iterations)
• Unique salt and IV per encryption operation

​

Performance Issues

​

Slow Terminal Response

• Delayed keystrokes in the web terminal
• Laggy terminal output

1. Check Network Latency:
   • WebSocket connections are affected by network latency
   • Test connection to the SuSHi server and target machine
2. Terminal Buffer Settings:
   • Adjust buffer size in controllers/ssh.go:150 (default: 1024 bytes)
   • Larger buffers reduce message frequency but increase latency
3. Heartbeat Configuration:
   • Heartbeat messages keep connections alive (controllers/ssh.go:134)
   • Adjust frequency if experiencing timeouts

​

High Memory Usage

1. Monitor active SSH connections
2. Check for connection leaks in the connection map
3. Ensure sessions are properly closed when terminals disconnect
4. Review log level (set to Info or Warning in production instead of Debug)

​

Docker and Container Issues

​

Container Fails to Start

docker logs sushi-backend
docker logs postgres

1. Missing environment variables
2. Database not ready when backend starts
3. Port conflicts
4. Volume permission issues

​

Database Data Persistence

volumes:
  - ./db/data:/bitnami/postgresql/data

​

Logging and Debugging

​

Enable Debug Logging

environment:
  - LOG_LEVEL=Debug

​

View Real-Time Logs

# All services
docker compose logs -f

# Specific service
docker compose logs -f sushi-backend

​

Common Log Messages

• JWT token: [token] - Successful authentication
• Connected to machine successfully - SSH connection established
• SSH connection stored successfully - Connection cached with UUID

• No SSH connection found for UUID - Invalid or expired connection ID
• Error reading WebSocket message - Client disconnected or network issue
• Failed to connect to machine - SSH connection failed

​

Getting Additional Help

1. Check the GitHub repository for known issues
2. Enable debug logging and review the logs for specific error messages
3. Open a GitHub issue with:
   • Error message and stack trace
   • Steps to reproduce
   • Environment details (OS, Docker version, etc.)
   • Relevant log excerpts