GuidesOnly show guides for your app
GuidesGuidesA database that won't connect throws one of a handful of errors, and each names its own cause. Here's the whole zoo across mysql2, pg, MongoDB, and redis — the exact codes, what they mean, and the fix.
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 |
Before decoding an error, know where your database actually lives — this is the single biggest cause of connection failures:
localhost. The page even shows a ready-made connection string. See Add a database.SERVER_PORT. From outside, connect to that server's public address: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.
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 |
Every one of those errors is really answering one of three questions:
ECONNREFUSED (reached the host, wrong port), ETIMEDOUT (never reached it), and ENOTFOUND (bad hostname) are all address problems — the credentials never even got tested. Fix the host and port first.ER_ACCESS_DENIED_ERROR, pg 28P01, redis NOAUTH/WRONGPASS, and Mongo Authentication failed are all credential problems — you reached the database, but the user or password is wrong. For Mongo, also check authSource matches the database that owns the user.Unknown database / does not exist means you connected and authenticated fine, but named a database that isn't there.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/dbname
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.