🚨 Logstash Error: 'Connection refused' — Cause, Fix, and Troubleshooting Guide

Overview

The Logstash jdbc input first loads the driver class, then opens a TCP connection to the database named in jdbc_connection_string. When the driver is fine but the TCP connect is rejected, the JVM raises ConnectException: Connection refused and the input reports it could not connect:

[ERROR][logstash.inputs.jdbc ][main] Unable to connect to database. Tried 1 times {:message=>"Java::JavaNet::ConnectException: Connection refused (Connection refused)"}

Depending on the driver you may also see the same underlying failure wrapped by Sequel and the connector:

Sequel::DatabaseConnectionError: Java::ComMysqlCjJdbcExceptions::CommunicationsException: Communications link failure

This is distinct from the could not load driver class error covered in the jdbc-driver-class guide. There the driver JAR was missing; here the driver loaded correctly and it was the network connection to the database that was refused. “Connection refused” specifically means something answered on the route and actively rejected the connect — usually nothing is listening on that host:port, or a firewall sent a reset — as opposed to a timeout, which means no answer at all.

Symptoms

• Java::JavaNet::ConnectException: Connection refused (Connection refused) or Communications link failure in logstash-plain.log.
• The input logs Unable to connect to database. Tried 1 times and emits no rows.
• Downstream indices stay empty even though the config is valid and the driver loads.
• nc -vz <db-host> <port> from the Logstash host fails or is refused.
• It appears after a DB restart, a host/port change, a network/firewall change, or a move to an environment where the DB only listens on localhost.

Common Root Causes

• Database is down — nothing is listening on the port, so the connect is refused.
• Wrong host or port — a typo or stale value in jdbc_connection_string points at a host:port with no listener.
• DB bound to localhost only — bind-address / listen_addresses restricts the listener to 127.0.0.1, so remote connects are refused.
• Firewall or security group — a rule blocks the Logstash host from reaching 3306/5432/1521, often surfacing as a reset.
• TLS required but not negotiated — the server rejects the plaintext connect because it demands SSL.

How to diagnose

Test raw TCP reachability from the Logstash host itself. This separates a network problem from anything in the Logstash config:

# Can the Logstash host even reach the DB port?
nc -vz db.internal 3306

# DNS resolves to the address you expect?
getent hosts db.internal

If nc is refused, check where the database is actually listening. Bound to 127.0.0.1 means remote connects will be refused:

# On the DB host: what address/port is the DB listening on?
ss -ltnp | grep -E ':3306|:5432|:1521'

# MySQL bind address / PostgreSQL listen addresses
grep -E '^bind-address|^listen_addresses' /etc/mysql/my.cnf /etc/postgresql/*/main/postgresql.conf 2>/dev/null

Then confirm the input’s connection string names the right host and port. Logstash .conf files use a Ruby-like DSL, so the input is shown as ruby:

input {
  jdbc {
    jdbc_driver_library    => "/usr/share/logstash/drivers/mysql-connector-j-8.4.0.jar"
    jdbc_driver_class      => "com.mysql.cj.jdbc.Driver"
    jdbc_connection_string => "jdbc:mysql://db.internal:3306/appdb"   # host:port must be reachable
    jdbc_user              => "logstash_ro"
    jdbc_password          => "${MYSQL_RO_PASSWORD}"
    statement              => "SELECT id, email, updated_at FROM users WHERE updated_at > :sql_last_value"
  }
}

Fixes

Point jdbc_connection_string at a host:port that is actually listening and reachable, and add sensible connect-timeout and SSL parameters. A corrected MySQL input looks like this:

input {
  jdbc {
    jdbc_driver_library    => "/usr/share/logstash/drivers/mysql-connector-j-8.4.0.jar"
    jdbc_driver_class      => "com.mysql.cj.jdbc.Driver"
    jdbc_connection_string => "jdbc:mysql://db.internal:3306/appdb?connectTimeout=15000&sslMode=REQUIRED"
    jdbc_user              => "logstash_ro"
    jdbc_password          => "${MYSQL_RO_PASSWORD}"
    schedule               => "*/5 * * * *"
    statement              => "SELECT id, email, updated_at FROM users WHERE updated_at > :sql_last_value"
    use_column_value       => true
    tracking_column        => "updated_at"
    tracking_column_type   => "timestamp"
  }
}

If the DB is bound to localhost, make it listen on the interface Logstash reaches (for MySQL set bind-address = 0.0.0.0 or a specific address; for PostgreSQL set listen_addresses), then restart the database. If a firewall is blocking the port, open it from the Logstash host to the DB:

# Open the DB port to the Logstash host (example: firewalld)
sudo firewall-cmd --add-rich-rule='rule family=ipv4 source address=10.0.0.5/32 port port=3306 protocol=tcp accept' --permanent
sudo firewall-cmd --reload

# Re-test reachability, then restart Logstash
nc -vz db.internal 3306
sudo systemctl restart logstash

Verify by tailing logstash-plain.log after the restart — the Connection refused message should stop and the scheduled statement should run.

What to watch out for

• “Connection refused” is not “connection timed out”: refused means something rejected the connect (nothing listening / a reset), while a timeout means no response — often a different firewall behavior.
• This is not the driver-class error — if the driver failed to load you would see ClassNotFoundException, not ConnectException. Confirm which one you actually have.
• A DB bound to 127.0.0.1 will refuse every remote connect no matter how correct your connection string is; fix the listener, not the string.
• If the server requires TLS, a plaintext connect is refused — set the driver’s SSL parameters (sslMode, ssl=true, etc.) to match.
• Add connectTimeout so a wrong host fails fast instead of hanging the input’s connect attempt.

Related

• Fix the Logstash jdbc input driver class error
• Restore a dead Logstash Elasticsearch output connection
• Resolve Logstash ‘No configuration found’ errors