How to fix Invalid catalog name in PostgreSQL

PostgreSQLBEGINNERHIGHUpdated Dec 27, 2025· 189 views

PostgreSQL error 3D000 means you specified a database name that doesn't exist or is misspelled. Fix it by verifying the database name exists and checking your connection string.

Quick fix

Fixes 3D000

psql -U postgres
  1. Verify the database exists
  2. Check your connection string
  3. Create the database if it doesn't exist
  4. Fix maintenance_database in multi-tenant setups
postgresql — error
psql -U postgres
Invalid catalog name

What this error means

In PostgreSQL, a "catalog" refers to a database. Error 3D000 "Invalid catalog name" occurs when your application attempts to connect to or use a database that doesn't exist in the PostgreSQL server. This is a connection-level error that prevents any queries from executing. The error can be triggered by: - Specifying a non-existent database name in your connection string - Mistyping the database name - Attempting to connect after a database has been dropped - Using a different database name than what was created during setup

Typical symptoms

  • Connection fails immediately when trying to connect to PostgreSQL
  • Application crashes with "SQLSTATE[3D000]" or error code 3D000
  • ORM migrations fail during database setup with "Invalid catalog name"
  • Application works with one database name but fails when configuration changes

Common causes

  1. Database name in connection string doesn't exist in PostgreSQL
  2. Database name is misspelled in the connection string or configuration
  3. Database was dropped or deleted but connection string wasn't updated
  4. Using wrong maintenance database (common in multi-tenant setups)
  5. Database hasn't been created yet during initial setup

How to fix "Invalid catalog name"

1Verify the database exists

Connect to PostgreSQL as a superuser and list all databases:

bash
psql -U postgres

Then in the PostgreSQL prompt:

sql
\l

This shows all databases. Look for the database name you're trying to connect to. If it doesn't appear in the list, you need to create it.

2Check your connection string

Verify the database name in your connection string matches exactly (case-sensitive). Common connection string formats:

bash
postgresql://user:password@localhost:5432/dbname

Ensure:
- The database name is spelled correctly
- No extra spaces or special characters
- The database exists (from step 1)

Check in:
- Environment variables (.env, .env.local)
- Configuration files (config.js, database.yml, etc.)
- Application code with hardcoded connections

3Create the database if it doesn't exist

If the database is missing, create it:

sql
CREATE DATABASE mydbname;

For specific character encoding:

sql
CREATE DATABASE mydbname
  ENCODING 'UTF8'
  LC_COLLATE 'C'
  LC_CTYPE 'C'
  TEMPLATE template0;

Then reconnect with the correct connection string.

4Fix maintenance_database in multi-tenant setups

Some tools (Ecto, Rails, etc.) use a "maintenance database" to create/drop other databases. By default it's "postgres", but some cloud providers use different names:

elixir
# Ecto example
config :myapp, MyApp.Repo, maintenance_database: "defaultdb"
ruby
# Rails example
adapter: postgresql
database: <%= ENV["DB_NAME"] %>
maintenance_db: defaultdb

Check your database hosting provider's documentation for the correct maintenance database name.

Advanced notes

PostgreSQL error codes follow the SQL standard. 3D000 specifically means "INVALID CATALOG NAME" in the Class 3D category. When catching this error in application code, check for SQLSTATE 3D000. In PL/pgSQL, you can catch it with: WHEN SQLSTATE '3D000' THEN ... Some hosted PostgreSQL providers (DigitalOcean, AWS RDS) create a default database with a different name than "postgres" - always check your provider's documentation. For connection pooling tools like PgBouncer, ensure the database exists in the PostgreSQL server, not just in PgBouncer's configuration.

Frequently asked questions

What does "3D000" mean?
In PostgreSQL, a "catalog" refers to a database. Error 3D000 "Invalid catalog name" occurs when your application attempts to connect to or use a database that doesn't exist in the PostgreSQL server. This is a connection-level error that prevents any queries from executing.
How do I fix "3D000"?
PostgreSQL error 3D000 means you specified a database name that doesn't exist or is misspelled. Fix it by verifying the database name exists and checking your connection string.
What causes "3D000"?
Database name in connection string doesn't exist in PostgreSQL Database name is misspelled in the connection string or configuration Database was dropped or deleted but connection string wasn't updated
Is the "3D000" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading