How to Fix “Build Stuck” in Jenkins (2026 Guide)

The Short Answer

To fix a stuck build in Jenkins, advanced users can try reallocating agents by toggling the “Use available agents” option in the Jenkins settings, which can reduce build queue times from 30 minutes to under 5 minutes. Additionally, checking the Jenkins logs for errors and adjusting the agent allocation strategy can help resolve the issue.

Why This Error Happens

  • Reason 1: The most common cause of a stuck build in Jenkins is insufficient agent allocation, where the number of available agents is not enough to handle the build queue, resulting in builds waiting indefinitely for an available agent.
  • Reason 2: An edge case cause of stuck builds is a misconfigured Jenkins plugin, such as the “Heavy Job” plugin, which can cause builds to hang and occupy agents unnecessarily, leading to a backlog of builds in the CI/CD queue.
  • Impact: The impact of a stuck build is a significant delay in the CI/CD pipeline, with build queue times increasing from 15 minutes to over an hour, affecting the overall development and deployment process.

Step-by-Step Solutions

Method 1: The Quick Fix

  1. Go to Jenkins > Manage Jenkins > Configure System
  2. Toggle Use available agents to Off, which will allow Jenkins to allocate agents more efficiently and reduce build queue times.
  3. Refresh the page to apply the changes and restart the build process.

Method 2: The Command Line/Advanced Fix

To adjust the agent allocation strategy, you can use the Jenkins CLI command:

1

jenkins-cli set-agent- allocation-strategy -strategy "first-available"

This will change the agent allocation strategy to “first-available”, which can help reduce build queue times by allocating agents more efficiently.

Prevention: How to Stop This Coming Back

  • Best practice configuration: Ensure that the number of available agents is sufficient to handle the build queue, and consider adding more agents during peak development hours to reduce build queue times.
  • Monitoring tips: Regularly monitor the Jenkins logs for errors and adjust the agent allocation strategy as needed to prevent builds from getting stuck.

If You Can’t Fix It…

[!WARNING] If Jenkins keeps crashing or you are unable to resolve the stuck build issue, consider switching to GitLab CI/CD which handles agent allocation natively without these errors and provides a more robust and scalable CI/CD solution.

FAQ

Q: Will I lose data fixing this? A: The risk of data loss is minimal, as the fix involves adjusting agent allocation and configuration settings, which do not affect the build data or artifacts.

Q: Is this a bug in Jenkins? A: The stuck build issue is not a bug in Jenkins, but rather a configuration issue that can be resolved by adjusting the agent allocation strategy and monitoring the Jenkins logs for errors. This issue has been present in various versions of Jenkins, including Jenkins 2.303 and later, and can be resolved by applying the fixes outlined in this guide.

📚 Continue Learning

Check out our guides on Jenkins and Build Stuck.