The Short Answer

To fix a “stuck” Jenkins pipeline, try toggling the agent offline by going to Jenkins > Nodes > [Node Name] > Configure and setting the node to offline, then back online. This simple step can resolve the issue in under 30 seconds, reducing the average stuck time from 15 minutes to near instant recovery.

Why This Error Happens

• Reason 1: The most common cause of a “stuck” Jenkins pipeline is an agent that is not properly configured or has become unresponsive, leading to a build queue that cannot be processed. For instance, if an agent is set to be always online but is experiencing network connectivity issues, it can cause the pipeline to hang indefinitely.
• Reason 2: An edge case cause could be a plugin or a custom script within the pipeline that is not properly handling errors or exceptions, causing the pipeline to freeze. This might happen when a plugin is updated or a new script is introduced without thorough testing.
• Impact: The impact of a “stuck” pipeline on CI/CD is significant, as it can halt the entire development and deployment process. This leads to delays in delivering new features or fixes to production, affecting both the development team’s productivity and the end-users’ experience.

Step-by-Step Solutions

Method 1: The Quick Fix

1. Go to Jenkins > Nodes > [Node Name] > Configure.
2. Toggle the Take this node offline option to Yes and then click Save.
3. Wait for a few seconds and then toggle it back to No and click Save again.
4. Refresh the Jenkins dashboard to see if the pipeline is now running.

Method 2: The Command Line/Advanced Fix

For a more advanced fix, especially if the issue persists, you can try restarting the Jenkins agent manually or adjusting the agent’s configuration through the command line.

1
2
3
4
5

# Stop the Jenkins agent
sudo service jenkins-agent stop

# Start the Jenkins agent
sudo service jenkins-agent start

Alternatively, you can adjust the jenkins-agent configuration file to include parameters that help manage its lifecycle and connectivity more effectively.

Prevention: How to Stop This Coming Back

• Best practice configuration: Regularly review and update your Jenkins and plugin versions to ensure you have the latest fixes and features. Also, implement a robust monitoring system to quickly identify when an agent goes offline or a pipeline gets stuck.
• Monitoring tips: Utilize Jenkins’ built-in monitoring features or integrate with external tools like Prometheus and Grafana to keep a close eye on your pipeline’s health and performance. Setting up alerts for when a pipeline stalls or an agent goes offline can help mitigate the impact of such events.

If You Can’t Fix It…

[!WARNING] If your Jenkins pipeline keeps crashing despite trying the above fixes, consider switching to GitLab CI/CD which handles agent management and pipeline orchestration more robustly without these errors, potentially saving you hours of troubleshooting time per week.

FAQ

Q: Will I lose data fixing this? A: Generally, fixing a “stuck” pipeline by toggling an agent offline and then back online does not result in data loss. However, if the issue is due to a more complex problem like a corrupted build or a misconfigured pipeline, there might be a risk of losing specific build data. Always back up your Jenkins data before making significant changes.

Q: Is this a bug in Jenkins pipeline? A: The “stuck” pipeline issue is not typically considered a bug in Jenkins itself but rather a symptom of misconfiguration, plugin issues, or environmental factors. Jenkins has a robust community and regular updates, with version 2.303 and later including several fixes related to agent management and pipeline stability. Checking the Jenkins version history and updating to the latest version can often resolve known issues.

📚 Continue Learning

Check out our guides on jenkins pipeline and Stuck.