​
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

Was this page helpful?