Sequelize "SequelizeConnectionRefusedError" in CI

By Daniel Zoghalchali·Latchkey

Sequelize could not open a connection to the database (ECONNREFUSED) when running migrations. The database is not listening yet (still starting) or the host/port is wrong - a connectivity problem, frequently a transient readiness race.

What this error means

sequelize-cli db:migrate fails with "SequelizeConnectionRefusedError: connect ECONNREFUSED". It often passes on retry once the database service container is up.

SequelizeConnectionRefusedError: connect ECONNREFUSED 127.0.0.1:5432
    at Client._connectionCallback (.../sequelize/lib/dialects/postgres/connection-manager.js)

Common causes

Database service not ready

The database container is still starting when sequelize-cli connects, so the connection is refused. Transient.

Wrong host/port in config

The config/config.json (or env) host/port does not match the reachable service, refusing every attempt.

Transient network blip

A brief connectivity drop can refuse a connection that succeeds moments later.

How to fix it

Wait for the database before migrating

until pg_isready -h 127.0.0.1 -p 5432; do sleep 1; done
npx sequelize-cli db:migrate

Verify the Sequelize config host/port

1. Confirm config/config.json (or DATABASE_URL) matches the CI service host/port.
2. Use 127.0.0.1 with a published port when connecting from the runner.
3. Retry once the service is healthy to confirm a transient cause.

How to prevent it

• Gate db:migrate on a readiness check.
• Keep the Sequelize config aligned with the CI network.
• On managed runners (Latchkey), self-healing auto-retries transient failures such as a database slow to accept connections.

Frequently asked questions

Related guides

References

• GitHub Actions documentation