Common Symptoms

Environment Stuck in Startup Phase

If your environment is stuck in the startup phase:

  1. Check network forwarding configuration:

    # If using UFW (Uncomplicated Firewall)
    grep FORWARD /etc/default/ufw
    sudo ufw status
    
    # If not using UFW, check iptables
    sudo iptables -L FORWARD
    
  2. If you see Chain FORWARD (policy DROP) in iptables or UFW’s forward policy is not set to ACCEPT:

    # For UFW
    sudo nano /etc/default/ufw
    # Set DEFAULT_FORWARD_POLICY="ACCEPT"
    sudo ufw reload
    
    # For iptables
    sudo iptables -P FORWARD ACCEPT
    
  3. Verify internet connectivity on the host machine

Runner Shows as Disconnected

If the runner appears disconnected in the UI:

  1. Check runner service status:

    # If running as a service
    sudo systemctl status gitpod-runner
    
  2. View logs for errors:

    journalctl -u gitpod-runner
    
  3. Verify:

    • Internet connectivity
    • System resources
    • Service configuration

Setup Validation Fails

CPU Virtualization Not Enabled

❌ System requirements validation failed:
• CPU virtualization not enabled
  1. Verify CPU virtualization support:
    grep -E 'svm|vmx' /proc/cpuinfo
    
  2. Enable virtualization in BIOS if supported
  3. Note: Most cloud VMs don’t support nested virtualization by default

UFW Forwarding Policy Error

❌ System requirements validation failed:
• UFW forwarding policy needs to be configured

Follow the steps in Environment Stuck in Startup Phase

Permission Issues

If you see capability or permission errors:

Error: failed to set capabilities on runner binary

This usually indicates an issue with the sudoers configuration. Check:

  1. Verify your sudoers configuration:

    sudo cat /etc/sudoers.d/gitpod-runner
    
  2. Ensure it contains the correct rules for your user and runner path:

    YOUR_USERNAME ALL=(root) NOPASSWD: /sbin/setcap cap_net_admin+ep /home/YOUR_USERNAME/gitpod-runner/bin/*/gitpod-runner
    YOUR_USERNAME ALL=(root) NOPASSWD: /sbin/setcap cap_net_admin+ep /home/YOUR_USERNAME/gitpod-runner/bin/*/cloud-hypervisor
    
  3. If the file doesn’t exist or has incorrect permissions, recreate it:

    sudo visudo -f /etc/sudoers.d/gitpod-runner
    
  4. Add the rules provided during the setup process, replacing YOUR_USERNAME in paths and username with your actual values

Resource Constraints

If environments fail to start or perform poorly:

  1. Check system resources:

    free -h
    df -h
    

    Runner data is stored in ~/gitpod-runner

  2. Solutions:

    • Stop unused environments
    • Increase system resources
    • Reduce concurrent environment count

Environment Limit Reached

If you hit the 10 environment limit:

  1. Check current environments in UI
  2. Delete unused environments
  3. Note: Deleted environments don’t count towards limit

Network Access Issues

If environments can’t access the network:

  1. Check forwarding configuration (see Environment Stuck in Startup Phase)
  2. Verify host machine network connectivity
  3. Check network interface configuration:
    ip link show
    

Repository Access Issues

If the runner can’t access repositories:

  1. Verify repository provider configuration in UI
  2. Check authentication status
  3. Try re-authenticating with repository provider

Viewing Logs

For systemd service:

# View all logs
journalctl -u gitpod-runner

# Follow logs in real-time
journalctl -u gitpod-runner -f

# View recent logs
journalctl -u gitpod-runner -n 100

For terminal mode, logs are printed to stdout.

Getting Help

If you can’t resolve an issue:

  1. Collect information:

    • Runner logs (from journalctl or terminal, also in ~/gitpod-runner/state/${RUNNER_ID}/log/)
    • Runner version (visible in UI)
    • System information
    • Error messages
    • Environment logs (in ~/gitpod-runner/state/${RUNNER_ID}/environments/${ENV_ID}/logs/*.log)
  2. Contact Gitpod support through:

    • Support chat (bottom right in UI)
    • Include collected information in your report

Prevention

To prevent common issues:

  1. Regular maintenance:

    • Keep runner updated
    • Monitor resource usage
    • Clean up unused environments
  2. Monitor logs for warnings:

    journalctl -u gitpod-runner
    
  3. Keep sufficient free resources:

    • Disk space
    • Memory
    • CPU capacity