StatsD client ECONNREFUSED on UDP 8125 (silent UDP, failing health check) in CI

StatsD sends metrics over UDP to localhost:8125. UDP has no connection, so sends appear to succeed even with no server, but a client error handler, a TCP-mode client, or a startup health check that pings the server will surface ECONNREFUSED and fail the test.

What this error means

A test using StatsD instrumentation logs "Error: connect ECONNREFUSED 127.0.0.1:8125" from the client`s error handler, or a health check that verifies the StatsD server fails while metrics themselves are silently dropped.

Error: connect ECONNREFUSED 127.0.0.1:8125
    at afterConnect (node:net:...)
# UDP send() succeeded but the error callback fired on the closed socket

Common causes

No StatsD server on 8125 in CI

The client targets localhost:8125. UDP hides the missing listener for send, but an error event or a connection-oriented client reports ECONNREFUSED.

A health check asserts the server is reachable

Startup code that pings the StatsD endpoint (or a TCP StatsD variant) fails when nothing listens, even though metric sends themselves do not throw.

How to fix it

Mock or disable StatsD in tests

1. Inject a mock/no-op StatsD client in the test environment.
2. Attach an error handler that ignores ECONNREFUSED so a missing server does not fail the run.
3. Skip any StatsD reachability health check under test.

const StatsD = require('hot-shots');
const client = new StatsD({ mock: true });   // no real UDP socket

Run a StatsD server as a service if needed

When a test asserts metrics are received, run a StatsD/Graphite service and point the client at it.

services:
  statsd:
    image: statsd/statsd:latest
    ports: ['8125:8125/udp']

How to prevent it

• Use a mock StatsD client in unit tests.
• Handle the client error event so ECONNREFUSED does not crash tests.
• Do not run a StatsD reachability health check in CI unless a server exists.

Related guides