Troubleshooting

SSH Connection Issues

Connection refused

• Verify the hostname/IP and port are correct
• Check the server's firewall allows SSH connections
• Ensure the SSH service is running on the server

Authentication failed

• Double-check username and password/key
• For key auth: ensure the key file has permissions 600
• Test with the native ssh command to isolate the issue

File Transfer Problems

Transfer hangs

• Check available disk space on both sides
• Verify write permissions on the destination directory
• Try a smaller file first to test connectivity

Permission denied

• Check file/directory permissions on the remote server
• Use the File Inspector (Cmd+I) to view and modify permissions

AI Chat Not Working

Provider not found

• Ensure Claude/Gemini/Codex CLI is installed
• Check the provider is detected in Settings > AI

API errors

• Verify your API key or authentication
• Check your internet connection
• Try switching to a different provider

MCP Server Issues

Port already in use

• Change the MCP port in Settings > MCP
• Check for other processes using the port: lsof -i :3847

Tools not appearing

• Ensure the tool group is enabled in Settings > MCP
• Restart the MCP server after changing settings

Cloud Sync Issues

• Verify your account is active in Settings > Remote & Backup
• Check your internet connection
• Manual sync available via the sync button in settings

Performance

• Close unused chat tabs (each loads conversation history)
• Reduce terminal scroll buffer if memory usage is high
• Disable the animated grid in Settings for better performance

Data Locations