Troubleshooting

This guide covers common issues you might encounter while using Siovos Desktop and their solutions.

License & Activation Issues#

License key not working / "Invalid license key"#

Possible causes:

• Typo in the license key
• Extra spaces before/after the key
• Wrong license for a different product

Solution:

1. Copy the license key directly from the email (don't retype it)
2. Make sure there are no spaces at the beginning or end
3. Verify it's a Siovos Desktop license (format: XXXX-XXXX-XXXX-XXXX)
4. If still failing, contact support with your purchase email

"Maximum devices exceeded"#

Cause: You've activated Siovos Desktop on more devices than your plan allows.

Solution:

1. Contact support@siovos.com to deactivate a device you no longer use
2. Or upgrade to a higher tier for more devices

"Unable to connect to license server"#

Possible causes:

• No internet connection
• Firewall blocking license.siovos.com
• Corporate proxy requiring configuration

Solution:

1. Check your internet connection
2. Verify you can access https://license.siovos.com in a browser
3. Check firewall/antivirus settings
4. If behind a corporate proxy, contact support for proxy configuration

Server Connection Issues#

SSH connection failed during deployment#

Possible causes:

• Wrong IP address
• SSH key doesn't match server's authorized_keys
• Firewall blocking SSH port
• SSH service not running

Solution:

# Verify you can SSH manually
ssh -i /path/to/key root@YOUR_IP

# Check that SSH is running on the server
systemctl status sshd

# Verify firewall allows port 22
ufw status

# Make sure the SSH key has correct permissions
chmod 600 /path/to/key

"Connection timeout"#

Possible causes:

• Server is down or unreachable
• Wrong IP address
• Network/firewall blocking access

Solution:

1. Ping the server: ping YOUR_IP
2. Check server status in your VPS provider's dashboard
3. Verify the IP address is correct
4. Make sure your local firewall isn't blocking outgoing connections

"Permission denied (publickey)"#

Cause: SSH key authentication is failing.

Solution:

1. Verify the public key is in the server's ~/.ssh/authorized_keys
2. Check key file permissions: chmod 600 ~/.ssh/id_rsa
3. Ensure you're selecting the private key (not the .pub file)
4. Try generating a new SSH key pair and adding it to the server

Deployment Issues#

"Insufficient memory" or deployment timeout#

Cause: Server doesn't have enough resources.

Solution:

1. Check server resources: free -h and df -h
2. Upgrade to a VPS with at least 8GB RAM
3. Reduce the number of services being deployed
4. Add swap space as temporary workaround (not recommended long-term)

"Ansible playbook failed" errors#

Solution:

1. Check the detailed error logs (click "Show Details")
2. Ensure server is running Debian 13: lsb_release -a
3. Update server packages: apt update && apt upgrade
4. Retry the deployment
5. If still failing, send the error logs to support

"Deployment stuck at X%"#

Possible causes:

• Slow network downloading large packages
• Task is waiting for user input (shouldn't happen, but possible)
• Process hung

Solution:

1. Wait at least 10 minutes - some tasks (like pulling Docker images) are slow
2. Check the detailed logs for the current task
3. If truly stuck (no log activity for 15+ minutes), cancel and retry
4. Check server load: ssh root@YOUR_IP top

VPN Connection Issues#

"Unable to connect to VPN"#

Possible causes:

• WireGuard not installed on your machine
• Firewall blocking UDP traffic
• VPN server not running
• Invalid configuration

Solution:

1. Install WireGuard if needed: WireGuard Installation
2. Check VPN server is running: ssh root@YOUR_IP systemctl status wg-quick@wg0
3. Verify firewall allows UDP port 51820
4. Try importing the WireGuard config manually

"VPN connected but can't access services"#

Possible causes:

• DNS not configured correctly
• Routing issues
• Services not actually running

Solution:

1. Verify VPN connection: ping 10.8.0.1 should work
2. Check if services are running on the server
3. Try accessing services by IP instead of hostname
4. Restart VPN connection

"VPN disconnects automatically"#

Possible causes:

• Network change (WiFi to Ethernet, etc.)
• Laptop went to sleep
• Unstable internet connection

Solution:

1. Enable "Auto-reconnect" in VPN settings
2. Check your internet connection stability
3. Ensure WireGuard service is allowed through firewall

SSL Certificate Issues#

"Certificate not trusted" browser warnings#

Cause: Root CA certificate not installed or not trusted in your system trust store.

Solution:

"Unable to install certificate" on macOS#

Cause: The configuration profile couldn't be opened or installed.

Solution:

1. Make sure you have administrator privileges on your Mac
2. Check that the profile appeared in System Settings → General → Device Management
3. If not visible, try clicking "Install SSL Certificate" again
4. Manually download the certificate from your server and install via Keychain Access

Browser still shows warnings after installation#

Possible causes:

• Browser has cached the old certificate status
• Profile not fully installed
• Different browser profile/container

Solution:

1. Verify the profile shows "Installed" in System Settings → Device Management
2. Completely quit your browser (all windows, check menu bar)
3. Clear browser SSL/certificate cache
4. Try incognito/private mode to rule out cache issues
5. Restart your computer if nothing else works

Performance Issues#

"Application is slow or unresponsive"#

Possible causes:

• Large log files
• Too many active deployments
• Low system resources

Solution:

1. Clear old deployment logs
2. Restart Siovos Desktop
3. Check system resources (CPU/RAM usage)
4. Close other resource-intensive applications

Getting Additional Help#

If you're still experiencing issues after trying these solutions:

1. Check the FAQ for quick answers
2. Email support@siovos.com with:
   • Detailed description of the issue
   • Steps to reproduce
   • Error messages or screenshots
   • Your license email (for verification)
   • Operating system and version
3. We typically respond within 24 hours