Fix Jenkins Build Timed Out and Configure Timeout Policies (2026)

Jenkins build timed out because the Jenkins agent failed to connect to the Jenkins controller within the configured timeout period, indicating a communication breakdown or resource exhaustion on the agent.

Agent Unreachable

Diagnosis: Check Jenkins controller logs for messages like "Agent disconnected" or "Agent timed out." On the agent machine, check jenkins-agent.log (or equivalent) for connection errors.

Cause: The Jenkins agent process crashed, was killed, or is stuck in a loop and unable to establish or maintain its WebSocket connection to the controller.

Fix:

1. Restart the agent process: sudo systemctl restart jenkins-agent (or equivalent for your OS/init system).
2. Check agent logs: Look for specific errors. If it’s repeatedly crashing, investigate the agent’s workspace or any recent code changes it might be trying to process.
3. Verify network connectivity: From the agent machine, ping <jenkins-controller-hostname-or-ip>. Ensure no firewalls are blocking port 50000 (or your configured agent port).

Why it works: Ensures the agent process is running and can communicate. Network issues prevent the initial handshake or heartbeat.

Agent Resource Exhaustion

Diagnosis: On the agent machine, run top or htop. Look for processes consuming high CPU or memory, especially the java process running the agent.

Cause: The agent machine is running out of memory or CPU, preventing the agent process from responding to the controller’s health checks. This is common on overloaded shared agents.

Fix:

1. Identify and stop rogue processes: If another process is hogging resources, stop it.
2. Increase agent RAM/CPU: If the machine is consistently maxed out, you need more powerful hardware or to reduce the load.
3. Configure agent JVM heap size: Edit the agent’s startup script (e.g., jenkins-agent.sh or the java command in systemd service) to include -Xmx4g (e.g., 4GB heap).

Why it works: Gives the agent process enough memory to operate correctly and respond to the controller.

Jenkins Controller Overload

Diagnosis: Check Jenkins controller system metrics (CPU, memory, disk I/O). Look for high load averages. Check Jenkins controller logs for "GC overhead limit exceeded" or other Java OutOfMemory errors.

Cause: The Jenkins controller itself is struggling due to too many jobs running, too many agents connected, or a memory leak in a plugin. This prevents it from processing agent heartbeats.

Fix:

1. Restart Jenkins controller: sudo systemctl restart jenkins (or equivalent).
2. Increase controller JVM heap size: Edit jenkins.xml (Windows) or jenkins.sh/jenkins.conf (Linux) and increase -Xmx (e.g., -Xmx8g for 8GB).
3. Offload work: Distribute jobs to more agents or use distributed builds.
4. Investigate plugins: Disable recently installed or updated plugins.

Why it works: A healthy controller is essential for managing agents. Increasing heap size allows it to handle more concurrent operations.

Network Latency/Packet Loss

Diagnosis: Use mtr or traceroute from the agent to the controller, and vice-versa, to identify packet loss or high latency hops.

Cause: Intermittent network issues between the agent and controller can cause the connection to appear dead to Jenkins, even if the agent process is running fine.

Fix:

1. Investigate network path: Work with your network team to resolve issues on problematic hops.
2. Increase agent connection timeout: In Jenkins Controller UI, go to Manage Jenkins -> Nodes -> <Your Agent Node> -> Configure. Increase In-use timeout to something higher, like 60 minutes.

Why it works: Gives the agent more leeway to recover from transient network glitches without being disconnected.

Incorrect Agent Configuration/Permissions

Diagnosis: Review the agent configuration in Jenkins (Manage Jenkins -> Nodes). Check the agent’s system user’s permissions on the agent machine to write to its workspace.

Cause: The agent process might be running as a user without the necessary permissions to write to its designated workspace directory, causing operations to fail silently and the agent to become unresponsive.

Fix:

1. Ensure correct user: Verify the jenkins user (or the user the agent runs as) has read/write access to the agent’s home directory and workspace. sudo chown -R jenkins:jenkins /path/to/jenkins/agent/home.
2. Check SELinux/AppArmor: If enabled, ensure policies allow the agent process to operate.

Why it works: The agent needs to be able to read and write files in its workspace to perform build tasks.

Build Job Timeout Exceeded

Diagnosis: In the Jenkins UI, navigate to the specific job. Click on Configure. Scroll down to Build Environment or General section and look for "Timeout" settings.

Cause: The job itself has a timeout configured that is shorter than the expected build duration. This is separate from the agent connection timeout.

Fix:

1. Increase job timeout: In the job configuration, under Build Environment (or General depending on Jenkins version/plugins), set a higher timeout value (e.g., 60 minutes, 1 hour).
2. Remove timeout: If the build should truly run indefinitely, uncheck the timeout option.

Why it works: Aligns the job’s maximum runtime with its actual expected duration.

The next error you’ll likely encounter is Agent was rejected if you’ve fixed the connection but the agent still has issues starting up or registering correctly.