Troubleshooting Guide

Find solutions to common issues with SwiftCloud. If you can't find your problem here, contact support.

Virtual Machines

VM Won't Start

Symptoms: VM shows "stopped" status, start button doesn't work

Solutions:

  1. Check your project balance — insufficient funds prevent VM startup
  2. Verify VM status in dashboard — look for error messages
  3. Try a hard reset from the power controls menu
  4. Check VNC console for boot errors
  5. If issue persists, contact support with VM ID

Can't Access VM via SSH

Symptoms: Connection timeout, "permission denied", or "connection refused"

Solutions:

  1. Verify IP address: Check VM details for current IP
  2. Check security groups: Ensure port 22 is open
  3. Test connectivity: ping your-vm-ip
  4. Verify SSH key: Ensure public key was added correctly
  5. Check username: Default is swift for Ubuntu/Debian
  6. Use VNC console: Access VM directly to check SSH service
# Test SSH connection
ssh -v swift@your-vm-ip

# If using password auth
ssh -o PreferredAuthentications=password -o PubkeyAuthentication=no swift@your-vm-ip

VM Running Slow

Symptoms: High latency, slow response times

Solutions:

  1. Check resource usage in dashboard (CPU, RAM, disk I/O)
  2. Upgrade to a larger VM size if resources are maxed out
  3. Check for runaway processes: top or htop
  4. Verify disk space: df -h
  5. Check for network congestion

VNC Console Not Working

Symptoms: Black screen, connection error, or timeout

Solutions:

  1. Ensure VM is powered on
  2. Refresh the console page
  3. Try a different browser (Chrome/Firefox recommended)
  4. Clear browser cache and cookies
  5. Check browser console for JavaScript errors
  6. Verify your internet connection

Billing & Payments

Low Balance Warning

Symptoms: Email alert about low balance

Solutions:

  1. Add funds immediately via Billing → Add Funds
  2. Use a coupon code if available
  3. Stop non-essential VMs to reduce burn rate
  4. Consider downsizing VMs to smaller tiers

Resource Suspended

Symptoms: VM stopped, "suspended" status

Solutions:

  1. Add funds to your project balance
  2. Wait for automatic unsuspension (within 24 hours)
  3. Or manually start VMs after adding funds
  4. Contact support if suspension was in error
Warning: Suspended resources are deleted after 90 days if not reactivated.

Coupon Not Working

Symptoms: "Invalid coupon" error

Solutions:

  1. Verify coupon code spelling (case-sensitive)
  2. Check expiration date
  3. Ensure coupon hasn't reached usage limit
  4. Verify coupon is applicable to your project type
  5. Contact support if issue persists

Domains & DNS

Domain Verification Failing

Symptoms: "Nameservers not configured" error

Solutions:

  1. Wait 24-48 hours after changing nameservers
  2. Verify nameservers at your registrar: 
    ns1.osystems.africa
ns2.osystems.africa
  3. Check with dig NS yourdomain.com
  4. Ensure no typos in nameserver configuration
  5. Contact your registrar if changes aren't saving

DNS Changes Not Propagating

Symptoms: DNS records not resolving after update

Solutions:

  1. Check TTL value — lower TTL = faster propagation
  2. Use dig A yourdomain.com to test
  3. Try from different networks (mobile vs WiFi)
  4. Flush local DNS cache: 
    # Windows
ipconfig /flushdns

# macOS
sudo dscacheutil -flushcache

# Linux
sudo systemd-resolve --flush-caches

Can't Add Domain

Symptoms: "Domain already exists" or validation error

Solutions:

  1. Check if domain is already in another project
  2. Remove http:// or www. prefix
  3. Ensure domain format is valid (e.g., example.co.zm)
  4. Verify you have Owner/Admin role in the project

Authentication

Can't Sign In

Symptoms: Login page errors, magic link not working

Solutions:

  1. Check spam folder for magic link email
  2. Magic links expire after 24 hours — request a new one
  3. Try Google OAuth instead
  4. Clear browser cookies and cache
  5. Try incognito/private browsing mode
  6. Verify email address spelling

Session Expires Frequently

Symptoms: Logged out unexpectedly

Solutions:

  1. Check "Remember me" option when signing in
  2. Ensure cookies are enabled in browser
  3. Add site to cookie/blocker exceptions
  4. Check browser settings for session timeout

Projects

Can't Access Project

Symptoms: "Access denied" or project not visible

Solutions:

  1. Verify you've been added to the project
  2. Check your role (Viewer has limited access)
  3. Ask project owner to re-send invitation
  4. Sign out and sign back in to refresh permissions

Can't Delete Project

Symptoms: Delete button disabled or error

Solutions:

  1. Delete or transfer all resources first
  2. Remove all team members
  3. Ensure zero balance (withdraw or donate funds)
  4. Only project Owner can delete projects

Network & Connectivity

Can't Reach Dashboard

Symptoms: Site won't load, timeout errors

Solutions:

  1. Check System Status page for outages
  2. Test from different network (mobile data)
  3. Clear browser cache
  4. Try different browser
  5. Check firewall/antivirus settings
  6. Disable browser extensions temporarily

API Requests Failing

Symptoms: 401, 403, or 500 errors

Solutions:

  1. 401 Unauthorized: Verify API key is valid
  2. 403 Forbidden: Check API key scopes
  3. 429 Rate Limited: Wait and retry, reduce request frequency
  4. 500 Server Error: Check status page, contact support
  5. Verify API endpoint URL is correct
  6. Check request headers and body format

Getting Help

Contact Support

If you can't resolve your issue:

  • Email: support@osystems.africa
  • Response Time: Within 24 hours
  • Include:
    • Your account email
    • Project ID or name
    • Resource ID (VM, domain, etc.)
    • Detailed description of the issue
    • Error messages (screenshots if possible)
    • Steps to reproduce

System Status

Check for known issues and outages at /status

← API Reference Contact Support