When your app can't reach its database, the driver throws a specific error — and the good news is there are only about six of them, repeated across every driver with different wording. Learn to read the code and the fix is obvious. This guide covers the four you'll use on Falix: mysql2 and pg (Postgres), the MongoDB driver, and redis.
| At a glance | |
|---|---|
| You need | An app that connects to a database, and the connection details from the Databases page (or your database server's Network page) |
| First move | Copy the exact error line — the code in it is the whole diagnosis |
First: are the connection details right?
Before decoding an error, know where your database actually lives — this is the single biggest cause of connection failures:
- A managed database (server Databases page: MySQL / PostgreSQL / MongoDB) runs on a shared DB host, not on your server. Use the host and port shown on that page — never
localhost. The page even shows a ready-made connection string. See Add a database. - A database application (the MongoDB / PostgreSQL / Redis app running in its own Falix server) binds your
SERVER_PORT. From outside, connect to that server's publicaddress:port; from another Falix server, use the Internal Network address. See Your own database server.
⚠️ Heads up:
localhostinside your app container means "this container" — not the database host. Pointing a managed-database connection atlocalhostis the classicECONNREFUSED.
The connection-error zoo
Read the code first; the fix follows from it.
| Error you'll see | Driver | What it means | Fix |
|---|---|---|---|
ECONNREFUSED (connect ECONNREFUSED host:port) |
all | Reached the host, but nothing is listening on that port | Wrong port, DB not started, or you used localhost — use the real host/port |
ETIMEDOUT / timeout expired / MongoServerSelectionError … timed out |
all | The host never answered | Wrong host, a Firewall drop rule, or the DB isn't exposed publicly |
ENOTFOUND (getaddrinfo ENOTFOUND host) |
all | The hostname doesn't resolve — a typo | Fix the host string |
ER_ACCESS_DENIED_ERROR — Access denied for user '…' (using password: YES) |
mysql2 | Wrong username or password | Recheck credentials; using password: NO means you sent none |
28P01 — password authentication failed for user "…" |
pg | Wrong password | Recheck the password |
NOAUTH Authentication required. |
redis | The server needs a password and you sent none | Put the password in the URL: redis://:PASSWORD@host:port |
WRONGPASS invalid username-password pair … |
redis | Wrong password | Fix the password in the URL |
Authentication failed (code 18) |
mongodb | Wrong user/password, or wrong authSource |
Fix credentials; managed Mongo needs ?authSource=dbname |
ER_BAD_DB_ERROR — Unknown database '…' |
mysql2 | The database name doesn't exist (or the user can't see it) | Fix the DB name to match the page |
3D000 — database "…" does not exist |
pg | The database name doesn't exist | Fix the DB name |
The three questions the codes answer
Every one of those errors is really answering one of three questions:
- Did I reach the right place?
ECONNREFUSED(reached the host, wrong port),ETIMEDOUT(never reached it), andENOTFOUND(bad hostname) are all address problems — the credentials never even got tested. Fix the host and port first. - Did I prove who I am?
ER_ACCESS_DENIED_ERROR, pg28P01, redisNOAUTH/WRONGPASS, and MongoAuthentication failedare all credential problems — you reached the database, but the user or password is wrong. For Mongo, also checkauthSourcematches the database that owns the user. - Did I ask for something that exists?
Unknown database/does not existmeans you connected and authenticated fine, but named a database that isn't there.
Keep credentials in the environment
Whatever the fix, put the host, user, and password in environment variables (a .env file) and read them in code — never paste them inline. A rotated password or a moved host then means editing one file, and your secrets stay out of Git. See Environment variables & secrets.
// One place, read from the environment
const url = process.env.DATABASE_URL; // e.g. postgresql://user:pass@host:port/dbnameIt connected before, now it times out
An app that worked and then starts timing out under load has usually run out of connections — every request opens a new one and never closes it, until the database refuses more. Use a connection pool (one shared, reused set of connections) instead of connecting per request. The pool is also where you set sensible timeouts so a stuck connection fails fast instead of hanging your whole app.
💡 Tip: On the free plan, a database application stops with your session timer like any other free server. If connections suddenly all fail, check the database server is still online before blaming your code.
Next steps
- Connect your app to a database
- Add a managed database
- node-postgres: node-postgres.com · MongoDB Node driver: mongodb.com/docs/drivers/node · node-redis: redis.io/docs/latest/develop/clients/nodejs