3D000FATALTier 1 — Safe✅ HIGH confidence

database does not exist

Category: Invalid Catalog NameVersions: All Postgres versions

What this means

A client attempted to connect to (or a statement referenced) a database that does not exist in the Postgres cluster. The lookup is performed against pg_database during the connection startup phase.

Why it happens

1Misspelled database name in the connection string
2The database has not been created yet
3The database was dropped while the application still had it in its connection string
4Database name is case-sensitive due to quotes used at creation time

How to reproduce

A connection string references a database that does not exist.

trigger — this will ERROR

-- From psql:
-- psql -d nonexistent_database
-- Results in: FATAL: database "nonexistent_database" does not exist

-- List existing databases from within a connected session:
SELECT datname FROM pg_database ORDER BY datname;

FATAL: database "nonexistent_database" does not exist

Fix 1: Create the database

When the database should exist but was never created.

fix

CREATE DATABASE myapp;

-- With owner and encoding:
CREATE DATABASE myapp
  OWNER = appuser
  ENCODING = 'UTF8'
  LC_COLLATE = 'en_US.UTF-8'
  LC_CTYPE = 'en_US.UTF-8';

Why this works

CREATE DATABASE calls the createdb() internal function which creates a new entry in pg_database and copies the template database (template1 by default) to a new data directory under PGDATA/base/<oid>/. After creation the database is immediately available for connections.

Fix 2: Verify the correct database name

When the database may exist under a slightly different name.

fix

-- Connect to postgres (the maintenance database) and list all databases:
SELECT datname FROM pg_database ORDER BY datname;

Why this works

pg_database is a cluster-wide catalog visible from any database in the cluster. Connecting to the postgres database (which always exists) and querying pg_database reveals all available database names with their exact casing.

What not to do

✗

Use the postgres maintenance database as an application database

Why it's wrong: The postgres database is reserved for administrative connections; application data should be in a dedicated database.

Sources

📚 Official docs: https://www.postgresql.org/docs/current/errcodes-appendix.html

📚 Feature docs: https://www.postgresql.org/docs/current/sql-createdatabase.html

🔧 Source ref: src/backend/postmaster/postmaster.c — InitPostgres()

📖 Further reading: CREATE DATABASE

Confidence assessment

✅ HIGH confidence

Stable and well-documented. The database lookup mechanism has been consistent across all versions. Edge case: each Postgres cluster has exactly one template0 and template1 database; these are always present and can be connected to for diagnostics.