Fix Jenkins Agent Connection Refused

What's Actually Happening

Jenkins controller cannot connect to agent nodes. The connection is refused due to network issues, firewall blocking, or incorrect agent configuration.

The Error You'll See

Connection refused:

```bash $ curl -s http://jenkins:8080/computer/agent-1/log

ERROR: Connection refused (Connection refused) java.net.ConnectException: Connection refused ```

SSH connection failed:

ERROR: SSH connection failed. Verification failed for host <agent-ip>
Authentication failed

Launch timeout:

ERROR: Agent launch timed out after 60 seconds
Agent did not connect within timeout

Agent offline:

```bash $ curl -s http://jenkins:8080/computer/api/json?tree=computer[displayName,offline]

{"computer": [{"displayName": "agent-1", "offline": true}]} ```

Why This Happens

1. 1.Agent not running - Agent process stopped or crashed
2. 2.Port blocked - Firewall blocking connection port
3. 3.SSH issues - SSH service not running or misconfigured
4. 4.Wrong credentials - Invalid SSH key or password
5. 5.Network issues - DNS resolution or routing problems
6. 6.Controller config - Wrong agent address or port

Step 1: Check Agent Status

```bash # Check if agent process running on agent machine: ssh agent-1 "ps aux | grep agent.jar"

# Or for systemd agent service: ssh agent-1 "systemctl status jenkins-agent"

# Check agent.jar location: ssh agent-1 "ls -la /opt/jenkins-agent/agent.jar"

# If agent not running, start it: ssh agent-1 "systemctl start jenkins-agent"

# Or manually: ssh agent-1 "java -jar agent.jar -jnlpUrl http://jenkins:8080/computer/agent-1/slave-agent.jnlp"

# Check agent logs: ssh agent-1 "tail /var/log/jenkins-agent.log" ```

Step 2: Check Network Connectivity

```bash # From Jenkins controller, check connectivity to agent: ping agent-1

# Check if agent IP correct: curl -s http://jenkins:8080/computer/agent-1/config.xml | grep -i host

# Test TCP connection (JNLP port, default varies): nc -zv agent-1 50000 # Example JNLP port

# For SSH agents, test SSH port: nc -zv agent-1 22

# Check DNS resolution: nslookup agent-1 dig agent-1

# If using IP: nc -zv 10.0.0.50 22

# Check routing: traceroute agent-1 ip route get 10.0.0.50 ```

Step 3: Check Firewall Rules

```bash # On agent machine, check firewall: ssh agent-1 "iptables -L -n -v"

# Check if Jenkins port blocked: ssh agent-1 "iptables -L -n | grep 22" ssh agent-1 "iptables -L -n | grep 50000"

# Allow Jenkins controller to connect: ssh agent-1 "iptables -I INPUT -p tcp -s <jenkins-ip> --dport 22 -j ACCEPT" ssh agent-1 "iptables -I INPUT -p tcp -s <jenkins-ip> --dport 50000 -j ACCEPT"

# For firewalld: ssh agent-1 "firewall-cmd --add-port=22/tcp --permanent" ssh agent-1 "firewall-cmd --reload"

# For ufw: ssh agent-1 "ufw allow from <jenkins-ip> to any port 22"

# Check SELinux: ssh agent-1 "getenforce" # If Enforcing, may block connections: ssh agent-1 "setsebool -P httpd_can_network_connect 1" ```

Step 4: Check SSH Configuration

```bash # Check SSH service on agent: ssh agent-1 "systemctl status sshd"

# If SSH not running: ssh agent-1 "systemctl start sshd"

# Check SSH config: ssh agent-1 "cat /etc/ssh/sshd_config | grep -E 'Port|PermitRootLogin|PasswordAuthentication'"

# Ensure settings allow Jenkins: Port 22 PermitRootLogin prohibit-password # Or yes for root PasswordAuthentication yes # Or use keys

# Check if Jenkins user can SSH: ssh agent-1 "id jenkins" # If user doesn't exist: ssh agent-1 "useradd -m jenkins"

# Test SSH from Jenkins controller: ssh jenkins@agent-1 "echo connected"

# Check SSH keys: ssh agent-1 "ls -la ~/.ssh/authorized_keys" ssh agent-1 "cat ~/.ssh/authorized_keys" | grep jenkins ```

Step 5: Verify Agent Credentials

```bash # In Jenkins UI: # Manage Jenkins > Credentials > System > Global credentials

# Check SSH credential type: curl -s http://jenkins:8080/credentials/store/system/domain/_/api/json | jq '.credentials[] | .id'

# Verify SSH key exists: # On Jenkins controller: ls -la /var/lib/jenkins/.ssh/id_rsa

# Test SSH key: ssh -i /var/lib/jenkins/.ssh/id_rsa jenkins@agent-1

# If key missing, create: ssh-keygen -t rsa -b 4096 -f /var/lib/jenkins/.ssh/id_rsa ssh-copy-id -i /var/lib/jenkins/.ssh/id_rsa.pub jenkins@agent-1

# Add key to Jenkins credentials: # Kind: SSH Username with private key # ID: agent-ssh-key # Username: jenkins # Private Key: Enter directly or from file ```

Step 6: Check Agent Launch Method

```bash # In Jenkins UI: # Manage Jenkins > Nodes > agent-1 > Configure

# Launch method options: # 1. Start agent via SSH # - Host: agent-1 or IP # - Port: 22 # - Credentials: SSH credential

# 2. Launch agent via execution of command on master # - Command: ssh jenkins@agent-1 java -jar agent.jar

# 3. Let Jenkins control this agent as a Windows service # - For Windows agents

# 4. Launch agents via SSH (new SSH slaves plugin) # - Same as option 1

# Check agent configuration: curl -s http://jenkins:8080/computer/agent-1/config.xml | grep -E 'host|port|launch'

# Verify configuration: <launcher class="hudson.plugins.sshslaves.SSHLauncher"> <host>agent-1</host> <port>22</port> <credentialsId>agent-ssh-key</credentialsId> </launcher> ```

Step 7: Check JNLP Connection

```bash # For JNLP agents (connection initiated from agent):

# Check Jenkins JNLP port: curl -s http://jenkins:8080/manage/configure | grep -i "TCP port"

# In Jenkins config: # TCP port for inbound agents: 50000 (or fixed port)

# If using fixed port, ensure it's accessible: nc -zv jenkins 50000

# On agent, run JNLP connection: ssh agent-1 "java -jar agent.jar -jnlpUrl http://jenkins:8080/computer/agent-1/slave-agent.jnlp -workDir /opt/jenkins-agent"

# If connection fails: ssh agent-1 "curl -v http://jenkins:8080/computer/agent-1/slave-agent.jnlp"

# Check agent JNLP secret: curl -s http://jenkins:8080/computer/agent-1/slave-agent.jnlp # Contains secret key

# Download agent.jar: ssh agent-1 "curl -O http://jenkins:8080/jnlpJars/agent.jar" ```

Step 8: Check Agent Work Directory

```bash # Check agent work directory exists: ssh agent-1 "ls -la /opt/jenkins-agent"

# Check permissions: ssh agent-1 "ls -la /opt/jenkins-agent" # Should be writable by jenkins user

# Fix permissions: ssh agent-1 "chown -R jenkins:jenkins /opt/jenkins-agent" ssh agent-1 "chmod -R 755 /opt/jenkins-agent"

# Check disk space: ssh agent-1 "df -h /opt/jenkins-agent"

# If disk full: ssh agent-1 "du -sh /opt/jenkins-agent/*" ssh agent-1 "rm -rf /opt/jenkins-agent/workspace/*"

# Check remoting.jar: ssh agent-1 "ls -la /opt/jenkins-agent/remoting.jar" # If missing, agent will download ```

Step 9: Restart Agent Connection

```bash # In Jenkins UI: # Manage Jenkins > Nodes > agent-1 > Disconnect # Then: Connect

# Via API: curl -X POST http://jenkins:8080/computer/agent-1/disconnect curl -X POST http://jenkins:8080/computer/agent-1/connect

# Via CLI: java -jar jenkins-cli.jar -s http://jenkins:8080 disconnect-agent agent-1 java -jar jenkins-cli.jar -s http://jenkins:8080 connect-agent agent-1

# Force reconnect: curl -X POST http://jenkins:8080/computer/agent-1/launch

# Restart agent process on agent machine: ssh agent-1 "systemctl restart jenkins-agent"

# Check connection status: curl -s http://jenkins:8080/computer/agent-1/api/json | jq '.offline' ```

Step 10: Monitor Agent Health

```bash # Create monitoring script: cat << 'EOF' > /usr/local/bin/check-jenkins-agent.sh #!/bin/bash

for agent in agent-1 agent-2 agent-3; do status=$(curl -s http://jenkins:8080/computer/$agent/api/json | jq -r '.offline') if [ "$status" = "true" ]; then echo "ERROR: $agent is offline"

# Try to reconnect curl -X POST http://jenkins:8080/computer/$agent/connect

# Send alert echo "$agent offline - attempted reconnect" | mail -s "Jenkins Agent Alert" admin@example.com else echo "OK: $agent is online" fi done EOF

chmod +x /usr/local/bin/check-jenkins-agent.sh

# Schedule check: */5 * * * * /usr/local/bin/check-jenkins-agent.sh >> /var/log/jenkins-agent-check.log

# Prometheus metrics: # Jenkins exposes agent metrics curl -s http://jenkins:8080/prometheus | grep jenkins_node

# Key metrics: # jenkins_node_online_count - online agents # jenkins_node_offline_count - offline agents # jenkins_node_busy_count - busy agents

# Alert for offline agents: - alert: JenkinsAgentOffline expr: jenkins_node_offline_count > 0 for: 5m labels: severity: warning annotations: summary: "Jenkins agent(s) offline" ```

Jenkins Agent Connection Checklist

Verify the Fix

```bash # After resolving connection issue

# 1. Check agent status in Jenkins curl -s http://jenkins:8080/computer/agent-1/api/json | jq '.offline' // false

# 2. Test SSH from controller ssh jenkins@agent-1 // Connected successfully

# 3. Check agent logs ssh agent-1 "tail /var/log/jenkins-agent.log" // No connection errors

# 4. Run test job on agent curl -X POST http://jenkins:8080/job/test/build?agent=agent-1 // Build started

# 5. Verify build completed curl -s http://jenkins:8080/job/test/lastBuild/api/json | jq '.result' // SUCCESS

# 6. Monitor agent health /usr/local/bin/check-jenkins-agent.sh // All agents OK ```

Related Issues

• [Fix Jenkins Agent Offline](/articles/fix-jenkins-agent-offline)
• [Fix Jenkins Agent Disconnected](/articles/fix-jenkins-agent-disconnected)
• [Fix Jenkins Build Queue Stuck](/articles/fix-jenkins-build-queue-stuck)