🚨 Jenkins Error: 'java.net.SocketTimeoutException: Read timed out' — Cause, Fix, and Troubleshooting Guide

Overview

java.net.SocketTimeoutException: Read timed out means a socket Jenkins opened stayed connected but the remote end stopped sending data before the read deadline elapsed. The connection succeeded — something is slow or silently dropping packets mid-transfer, not refusing the connection outright.

java.net.SocketTimeoutException: Read timed out
	at java.base/java.net.SocketInputStream.socketRead0(Native Method)
	at hudson.remoting.Channel ...
	Caused: java.io.IOException: Failed to load https://updates.jenkins.io/update-center.json

It shows up in three broad places: the controller reaching out (update center, plugin downloads, an external HTTP call in a pipeline), the controller-to-agent remoting channel (ping/keepalive), and SCM fetches. The trace’s Caused by/last URL tells you which one.

Symptoms

• Plugin manager fails with “Failed to load update center” and a Read timed out stack trace.
• Builds fail during an external HTTP call (httpRequest, curl, artifact upload/download) after a long hang.
• Agents disconnect with Ping failed. Terminating the channel or Read timed out in the agent log, then reconnect.
• SCM operations (git fetch, svn checkout) stall and then abort with a socket read timeout.
• The problem correlates with a corporate proxy, a firewall with idle-connection reaping, or a slow/overloaded remote host.
• Short requests succeed; large downloads or long-lived idle connections fail.

Common Root Causes

• Missing or misconfigured HTTP proxy — the controller cannot reach updates.jenkins.io directly and no proxy is set, so requests hang until the read timeout.
• Firewall/NAT idle-timeout reaping — a stateful firewall drops idle TCP connections; the agent remoting channel or a long download goes silent and Jenkins reads a dead socket until it times out.
• Slow or overloaded remote endpoint — the update center mirror, artifact repo, or SCM server is slow to respond; the default read timeout is too short for the transfer.
• DNS or routing latency — intermittent DNS resolution or an asymmetric route makes responses arrive too late.
• Agent-to-controller network jitter — high latency or packet loss on the JNLP/inbound-agent channel trips the remoting ping timeout.
• TLS/proxy interception adding latency — a deep-packet-inspection proxy buffers and re-encrypts traffic, slowing large responses past the timeout.

How to diagnose

Identify which socket timed out from the trace. A Caused by URL pointing at updates.jenkins.io is the update center; hudson.remoting.Channel frames point at the agent channel; a git/SCM frame points at source control.

Test connectivity and latency from the controller host (not your laptop):

# Reachability + latency to the update center or SCM
curl -v --max-time 30 https://updates.jenkins.io/update-center.json -o /dev/null
time curl -sSL https://jenkins.example.com/ -o /dev/null

# DNS resolution timing
dig +stats updates.jenkins.io | tail -5

Check the current proxy config in Manage Jenkins → System → HTTP Proxy Configuration, and confirm the JVM sees the same values:

# On the controller: what proxy/timeouts does the Jenkins process have?
ps -ww -p "$(pgrep -f jenkins.war)" -o args= | tr ' ' '\n' | grep -iE 'proxy|timeout|remoting'

For agent-channel timeouts, read the agent log (Manage Jenkins → Nodes → agent-01 → Log) and the controller’s journalctl:

journalctl -u jenkins --since '30 min ago' | grep -iE 'timed out|ping|remoting|SocketTimeout'

Use the Script Console to test an outbound call with the controller’s own JVM/proxy settings:

def url = new URL('https://updates.jenkins.io/update-center.json')
def c = url.openConnection()
c.connectTimeout = 10000; c.readTimeout = 30000
println "HTTP ${c.responseCode} in bytes: ${c.inputStream.bytes.length}"

Fixes

1. Configure the HTTP proxy correctly

Set the proxy in Manage Jenkins → System → HTTP Proxy Configuration (host, port, no-proxy hosts). For the JVM and CLI/plugin tooling, also set it in JENKINS_JAVA_OPTIONS (or /etc/default/jenkins / the systemd unit):

# /etc/systemd/system/jenkins.service.d/override.conf
[Service]
Environment="JENKINS_JAVA_OPTIONS=-Dhttp.proxyHost=proxy.example.com -Dhttp.proxyPort=3128 \
 -Dhttps.proxyHost=proxy.example.com -Dhttps.proxyPort=3128 \
 -Dhttp.nonProxyHosts=localhost|127.0.0.1|*.internal.example.com"

Reload and restart: systemctl daemon-reload && systemctl restart jenkins.

2. Increase the read/connect timeouts for slow endpoints

The update-center and general URL timeouts are JVM system properties. Raise them when a mirror is genuinely slow:

# Append to JENKINS_JAVA_OPTIONS
-Dhudson.model.UpdateCenter.checkUpdateAlternativeUrl=... \
-Dsun.net.client.defaultReadTimeout=60000 \
-Dsun.net.client.defaultConnectTimeout=20000

For a pipeline httpRequest step, set the timeout explicitly rather than relying on defaults:

httpRequest url: 'https://artifacts.example.com/build.tar.gz',
            timeout: 120,          // seconds
            quiet: false

3. Keep the agent channel alive through firewalls

Idle-connection reaping is the usual cause of remoting read timeouts. Shorten the ping interval so the channel is never idle long enough to be reaped, and enable TCP keepalive:

# On the controller JVM (JENKINS_JAVA_OPTIONS):
-Dhudson.remoting.Engine.socketTimeout=300000 \
-Dhudson.slaves.ChannelPinger.pingIntervalSeconds=120 \
-Dhudson.slaves.ChannelPinger.pingTimeoutSeconds=240

On inbound (JNLP) agents, pass -tcpKeepAlive / ensure the launch command keeps the socket warm, and align the firewall idle timeout to be longer than the ping interval.

4. Fix DNS / routing and prefer a closer mirror

If dig shows slow or intermittent resolution, pin a reliable resolver on the controller host and/or point the update center at a fast regional mirror in Manage Jenkins → Plugins → Advanced → Update Site. Verify the SCM/artifact hosts resolve consistently from the controller and every agent.

5. Retry transient network steps in the pipeline

Wrap genuinely flaky network calls so a one-off timeout recovers:

retry(3) {
  timeout(time: 3, unit: 'MINUTES') {
    sh 'curl -fSL --retry 3 https://artifacts.example.com/build.tar.gz -o build.tar.gz'
  }
}

What to watch out for

• Raising timeouts hides, but does not fix, a broken proxy or a firewall reaping connections — always confirm reachability first.
• The GUI proxy setting and the JVM -Dhttp.proxyHost are separate; plugin CLI/downloader code may use the JVM one, so set both.
• no_proxy/nonProxyHosts must include internal SCM and agent hosts, or internal traffic gets routed through (and stalled by) the external proxy.
• A ping interval longer than the firewall’s idle timeout guarantees agent drops — keep pings well under it.
• Don’t confuse Read timed out (socket alive, no data) with Connection refused (nothing listening) or Could not resolve host (DNS) — the fix differs for each.

Related

• Jenkins Error: ‘hudson.remoting.ChannelClosedException’ — when the timed-out agent channel actually closes.
• Jenkins Error: ‘Agent went offline during the build’ — the build-facing symptom of a dropped remoting connection.
• GitLab CI Error: ‘Could not resolve host’ — the DNS-resolution failure to rule out before blaming timeouts.