EC
Errno::ECONNREFUSED
RubyERRORNotableNetwork

Connection refused by remote host

Quick Answer

Verify the target service is running and listening on the expected host and port; implement retry logic with exponential backoff.

What this means

Raised when a TCP connection attempt is actively refused by the target host — meaning the host is reachable but nothing is listening on the target port. Maps to POSIX errno 111.

Why it happens
  1. 1Target service is not running or not yet started
  2. 2Wrong host or port in configuration
  3. 3Firewall or security group blocking the port

Fix

Retry with exponential backoff

Retry with exponential backoff
require 'net/http'

retries = 0
begin
  response = Net::HTTP.get_response(uri)
rescue Errno::ECONNREFUSED => e
  raise if retries >= 3
  retries += 1
  sleep(2 ** retries)
  retry
end

Why this works

Exponential backoff gives the target service time to start up before each retry attempt.

Code examples
Reproducing the errorruby
require 'socket'
TCPSocket.new('localhost', 9999)
# Errno::ECONNREFUSED: Connection refused - connect(2) for localhost:9999
Rescue in HTTP clientruby
begin
  response = http.get('/api/data')
rescue Errno::ECONNREFUSED
  raise ServiceUnavailableError, 'Could not reach upstream service'
end
Check with socket before connectingruby
def port_open?(host, port)
  TCPSocket.new(host, port).close; true
rescue Errno::ECONNREFUSED, Errno::ETIMEDOUT
  false
end
Sources
Official documentation ↗

Ruby Core Documentation

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Ruby errors