SQLSTATE / CLASS 3D · INVALID CATALOG NAME

3D000

invalid_catalog_name

SQLSTATE: 3D000
Condition name: invalid_catalog_name
Class: Invalid Catalog Name
Source macro: ERRCODE_INVALID_CATALOG_NAME
Evidence: Observed at runtime in the source evidence

Analysis & operational context

English SQLSTATE atlas: authored explanations and source/runtime evidence are separate from the manual definitions. View source ↗

At a glance

SQLSTATE 3D000 is invalid_catalog_name in Class 3D. 3D000 identifies an invalid database/catalog name. It can occur before startup completes when a requested database is absent, and fixed dbcommands.c paths also emit it while a SQL command resolves a missing database/template. The selected startup case reports C=3D000, S=FATAL, database "<generated>" does not exist; that is one phase, not the whole class.

Meaning

The code covers database/catalog resolution in more than one phase. postinit.c emits the selected startup FATAL when the requested database does not exist, while dbcommands.c uses the same condition for SQL commands that resolve a missing database or template. The startup record is therefore one concrete producer, not a universal description of every 3D000.

Treat the phase as part of the diagnosis. A startup DSN for a missing database produces a server FATAL and no session-level transaction; a SQL command such as an administrative database/template lookup can produce an ERROR inside an existing session, where normal rollback or savepoint recovery applies. The code alone does not tell you which phase failed.

Phase guide

Phase	Fixed producer	Recovery boundary
Startup database selection	`postinit.c` reports `database "%s" does not exist` as `FATAL`.	Fix the DSN or create/rename the database from a control database, then make a fresh connection. There is no session to roll back.
SQL command or template lookup	`dbcommands.c` uses `3D000` while handling an administrative command.	Inspect the command and its transaction; an `ERROR` inside an explicit transaction requires `ROLLBACK` or an intentional savepoint before unrelated work.

Diagnosis

Check the database name, whether it was renamed or dropped, the command phase, and which control database is available. The selected collector is a raw server ErrorResponse record, not csvlog/jsonlog; raw startup and psycopg are independent attempts. The selected runs use independent startup attempts: psycopg reports driver SQLSTATE null and no transaction, while the raw server ErrorResponse and a fresh known-database probe establish the server code and recovery path. Do not confuse a missing database with 3F000 schema lookup.

For startup failures, compare the exact database parameter after client-side defaults, URL decoding, and environment expansion; then inspect the raw server C, S, and M fields. For an already-connected SQL command, capture the command text and transaction state separately. The successful control-database probe proves only that a new session can be established, not that the original missing-database attempt had a transaction.

Response

Use an existing control database to inspect or create the intended database, or correct the DSN/command target, then establish a new connection. A pre-session failure has no session-level ROLLBACK; SQL command paths must be repaired in their owning administrative transaction and rechecked against the intended catalog.

If the database was intentionally removed, repair the application target or migration rather than retrying the same startup request. If an administrative command failed after a session existed, recover that transaction before issuing catalog changes. Reconcile any work sent by another connection before repeating it; the startup failure itself did not execute SQL in the missing database.

Observed diagnostics

The selected startup branch emits FATAL with primary database "%s" does not exist; the database name is dynamic. Fixed SQL-command paths use the same SQLSTATE but can have different surrounding operation and transaction boundaries. A client-side startup exception without the server ErrorResponse is insufficient.

The selected name c3d000_missing_cff0e8d38be4 is generated by the run. The server ErrorResponse is C=3D000, S=FATAL; psycopg's startup sqlstate=null and the known-database probe are separate attempts, not additional views of one session.

Representative case

The registry contains the probe used after the startup ErrorResponse. The trigger uses a generated database name on a fresh startup connection, so no SQL statement can reproduce that pre-session failure.

SELECT 1;

The selected 18.6 server ErrorResponse is C=3D000, S=FATAL, database "c3d000_missing_cff0e8d38be4" does not exist. The driver startup diagnostic has SQLSTATE null; the failed connection has no transaction, while the known-good probe returned 1 and IDLE.

The downloadable case and evidence projections are 3D000 case JSON and authored evidence. The runner manifest is verify/cases/3D000/cases.json; the page SQL is checked against its shared registry before publication.

Versions

The generated facts table records the locked catalogue snapshots and earliest observed definition. The selected natural runtime scope is PostgreSQL 18.6 and 10.21; this does not infer behavior for every intermediate release.

Sources

src.postinit-missing-db.18.6 — src/backend/utils/init/postinit.c at REL_18_6 commit 724edf9bde9d356724ad384a2e196edc3c9f80f7; fixed blob SHA-256 abcf80637b153d3aa6f0d2b600943af0a2b4d9a393d05a844db91f8b6b66d0d7 (source).
src.postinit-missing-db.10.23 — src/backend/utils/init/postinit.c at REL_10_23 commit 02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4; fixed blob SHA-256 be912628b29f34afc7b7fbc9d2f480c5ac9cb6ce013a1d992fc7415a311a95ed (source).
src.dbcommands-missing-database.18.6 — src/backend/commands/dbcommands.c at REL_18_6 commit 724edf9bde9d356724ad384a2e196edc3c9f80f7; fixed blob SHA-256 64b77d2197dce16eb1ad19d8168382459d621a03df0b00be157f7db39ca22acf (source).
src.dbcommands-missing-database.10.23 — src/backend/commands/dbcommands.c at REL_10_23 commit 02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4; fixed blob SHA-256 cf9e069415deb7d50ef931048616ae7f9a459d6db64e3d54a0062e8334970ce6 (source).
src.calls.REL_18_6 / src.calls.REL_10_23 — fixed local call scans, SHA-256 9ee8a0e81d8f0825c5c1ae45583439859a26e602bdd4ce2f2a62aa278867ccbf / 00d16d3eb01b71ccf1b245c8f3102f9d0ec9f36fb02777b8dd1b99fcb263040c; these scans preserve the resolved call context used by the claims.

Source evidence

Evidence belongs to the frozen source and runtime versions listed here. It is not a runtime verification of the selected manual version.

3D000 is the invalid_catalog_name condition in Class 3D.

Method: Read the fixed errcodes.txt definition and the locked catalogue metadata.

Limits: Directory identity does not identify every backend or client path.

src.errcodes.18.6

The fixed source paths associated with 3D000 report the condition in the mechanism selected for this page.

Method: Trace the resolved source call records at the fixed release commits and compare their dynamic message fields.

Limits: Other calls can retain the same SQLSTATE with different context or text.

src.postinit-missing-db.18.6 src.postinit-missing-db.10.23 src.dbcommands-missing-database.18.6 src.dbcommands-missing-database.10.23

The selected invalid_database case passed with the expected structured diagnostics, recovery assertions, and cleanup on PostgreSQL 18.6 and 10.21.

Method: Run the shared registry case on isolated runner-owned latest and PG10 targets; inspect the final summaries and raw results.

Limits: This covers the selected case and versions only; it does not generalize to every driver, proxy, or intermediate release.

snippet-registry.3D000 manifest.3D000

The selected postinit.c startup path emits 3D000 as FATAL before a session transaction exists, while fixed dbcommands.c paths use the same code in an already-connected SQL command where normal ERROR rollback or savepoint recovery applies.

Method: Compare the fixed startup and SQL-command source paths with the official transaction recovery contract and the selected startup runtime.

Limits: The selected runtime covers the startup missing-database path; the SQL-command phase is source-confirmed and has no selected natural runtime in this batch.

src.postinit-missing-db.18.6 src.dbcommands-missing-database.18.6 doc.transactions.18

The locked catalogue records 3D000 in the listed snapshots; the runtime comparison here is limited to PostgreSQL 18.6 and 10.21.

Method: Read the generated facts block and locked manifest, then compare the selected target summaries.

Limits: Presence in a definition file is not an exact behavioral introduction; the two runtime targets do not prove all middle versions.

src.errcodes.18.6 src.calls.REL_18_6 src.calls.REL_10_23

src/backend/utils/errcodes.txt · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7
raw/calls/REL_18_6.jsonl · REL_18_6 ·
raw/calls/REL_10_23.jsonl · REL_10_23 ·
src/backend/utils/init/postinit.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7
src/backend/utils/init/postinit.c · REL_10_23 ·
02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4
src/backend/commands/dbcommands.c · REL_18_6 ·
724edf9bde9d356724ad384a2e196edc3c9f80f7
src/backend/commands/dbcommands.c · REL_10_23 ·
02991e79f8f58bc208f05dcc8af0c62dbe0a6ea4
doc/src/sgml/xact.sgml · PG18-docs ·
724edf9bde9d356724ad384a2e196edc3c9f80f7
verify/cases/3D000/cases.json · workspace ·
verify/cases/3D000/snippets.json · workspace ·

Message templates

explicit FATAL · message.missing-database

Primary

database "%s" does not exist

Reproduction & repair cases

invalid_database · PG 10, 18

Preconditions

A runner-owned disposable target is provisioned.

Trigger: Attempt startup against a generated database name that does not exist.

Expected assertions

The selected server diagnostic has the expected SQLSTATE
The selected recovery/probe assertions pass
Runner-owned resources are cleaned up

Repair: Follow the case-specific repair statements and verify the resulting state.

Cleanup: Drop the case schema with an owner connection.

Recorded runtime evidence

18.6 (Homebrew) · passed

Run: 3D000-conn-contract-latest

Disposable runner-owned target only; this is a bounded mechanism case, not a guarantee for every client or network path.

{
  "probe": 1,
  "collector": {
    "primary": "database \"c3d000_missing_cff0e8d38be4\" does not exist",
    "severity": "FATAL",
    "sqlstate": "3D000"
  },
  "diagnostic": {
    "text": "connection failed: connection to server at \"127.0.0.1\", port 60025 failed: FATAL:  database \"c3d000_missing_cff0e8d38be4\" does not exist",
    "context": null,
    "severity": null,
    "sqlstate": null,
    "table_name": null,
    "column_name": null,
    "schema_name": null,
    "source_file": null,
    "source_line": null,
    "message_hint": null,
    "datatype_name": null,
    "exception_type": "OperationalError",
    "internal_query": null,
    "message_detail": null,
    "constraint_name": null,
    "message_primary": null,
    "source_function": null,
    "internal_position": null,
    "statement_position": null,
    "severity_nonlocalized": null
  },
  "probe_status": "IDLE",
  "server_error": {
    "C": "3D000",
    "F": "postinit.c",
    "L": "1016",
    "M": "database \"c3d000_missing_cff0e8d38be4\" does not exist",
    "R": "InitPostgres",
    "S": "FATAL",
    "V": "FATAL"
  },
  "missing_database": "c3d000_missing_cff0e8d38be4",
  "failed_connection_has_no_transaction": true
}

10.21 (Debian 10.21-1.pgdg90+1) · passed

Run: 3D000-conn-contract-pg10