Troubleshooting Linux Runners
Common Symptoms
Environment Stuck in Startup Phase
If your environment is stuck in the startup phase:
-
Check network forwarding configuration:
-
If you see
Chain FORWARD (policy DROP)
iniptables
or UFW’s forward policy is not set to ACCEPT: -
Verify internet connectivity on the host machine
Runner Shows as Disconnected
If the runner appears disconnected in the UI:
-
Check runner service status:
-
View logs for errors:
-
Verify:
- Internet connectivity
- System resources
- Service configuration
Setup Validation Fails
CPU Virtualization Not Enabled
- Verify CPU virtualization support:
- Enable virtualization in BIOS if supported
- Note: Most cloud VMs don’t support nested virtualization by default
UFW Forwarding Policy Error
Follow the steps in Environment Stuck in Startup Phase
Permission Issues
If you see capability or permission errors:
This usually indicates an issue with the sudoers configuration. Check:
-
Verify your sudoers configuration:
-
Ensure it contains the correct rules for your user and runner path:
-
If the file doesn’t exist or has incorrect permissions, recreate it:
-
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:
-
Check system resources:
Runner data is stored in
~/gitpod-runner
-
Solutions:
- Stop unused environments
- Increase system resources
- Reduce concurrent environment count
Environment Limit Reached
If you hit the 10 environment limit:
- Check current environments in UI
- Delete unused environments
- Note: Deleted environments don’t count towards limit
Network Access Issues
If environments can’t access the network:
- Check forwarding configuration (see Environment Stuck in Startup Phase)
- Verify host machine network connectivity
- Check network interface configuration:
Repository Access Issues
If the runner can’t access repositories:
- Verify repository provider configuration in UI
- Check authentication status
- Try re-authenticating with repository provider
Viewing Logs
For systemd service:
For terminal mode, logs are printed to stdout.
Getting Help
If you can’t resolve an issue:
-
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
)
- Runner logs (from
-
Contact Gitpod support through:
- Support chat (bottom right in UI)
- Include collected information in your report
Prevention
To prevent common issues:
-
Regular maintenance:
- Keep runner updated
- Monitor resource usage
- Clean up unused environments
-
Monitor logs for warnings:
-
Keep sufficient free resources:
- Disk space
- Memory
- CPU capacity
Was this page helpful?