Error codes

Generated from the error-code union types of @sezzlee/postgres-mcp 0.2.1.

A tool that fails answers with isError: true and one text item holding a JSON object with three fields: error, a stable machine code from this page; message, what went wrong; and recovery, what the next call should do differently. Branch on error, never on message.

This is the answer to describe_table {"schema":"sezzlee_shop","table":"orders"} from a server started with an address where no PostgreSQL is listening:

json

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\":\"connection_failed\",\"message\":\"connect ECONNREFUSED 127.0.0.1:9 (ECONNREFUSED)\",\"recovery\":\"Check database reachability and verified TLS settings.\"}"
    }
  ],
  "isError": true
}

The text item, parsed:

json

{
  "error": "connection_failed",
  "message": "connect ECONNREFUSED 127.0.0.1:9 (ECONNREFUSED)",
  "recovery": "Check database reachability and verified TLS settings."
}

The server has 16 codes.

Arguments and paging

Code	Meaning
`invalid_argument`	An argument the tool does not declare, a value of the wrong type, or a missing required argument. The recovery lists the arguments the tool accepts. A statement PostgreSQL refuses to compile is not this code: it answers `query_failed`, or `object_not_found` for an unknown table or column.
`invalid_cursor`	`cursor` is not a token `search_catalog` returned. Call it again without a cursor.
`stale_cursor`	The catalogue was read again, by `refresh` or because the cached copy expired, or the search arguments changed since the cursor was issued. Start again without a cursor.
`resource_limit`	The request would exceed a fixed budget: too many calls are already waiting for a connection, the first row of a result does not fit the response, a table has more than 512 columns, or a single object has more columns than the catalogue index holds. See Limits.

Connection

Code	Meaning
`connection_failed`	The server could not be reached, or the connection dropped: a wrong host or port, a firewall, a server that does not offer TLS when `SEZZLEE_POSTGRES_SSL_MODE` asks for it, a certificate `verify-full` cannot verify or that does not name the configured host, a server that is shutting down or restarting, or no answer within the connect timeout.
`authentication_failed`	PostgreSQL refused the login: a wrong user or password, or no `pg_hba.conf` entry that admits this role from this address with this encryption setting. Check `SEZZLEE_POSTGRES_USER`, `SEZZLEE_POSTGRES_PASSWORD` and `SEZZLEE_POSTGRES_SSL_MODE`.
`database_unavailable`	PostgreSQL has no database with the configured name (SQLSTATE 3D000). Check `SEZZLEE_POSTGRES_DATABASE`. A role that exists but may not connect to the database is refused with `permission_denied` instead.

Queries

Code	Meaning
`write_not_permitted`	No query ran, or PostgreSQL stopped it. Either the connected role is a superuser, can create roles or replicate, or is a member of `pg_read_server_files`, `pg_write_server_files`, `pg_execute_server_program` or `pg_signal_backend`, or its privileges could not be verified: `run_query` answers only for another role, and `describe_connection` reports what was measured as `principalPosture`. Or the statement guard refused the text: it does not begin with `SELECT` or `WITH`, holds more than one statement, is empty, leaves a string, quoted name or comment open, uses a `U&"…"` name, or calls a function that signals another session, takes a session lock, writes outside the transaction or runs SQL text the guard cannot see. Or the statement passed the guard and PostgreSQL refused it because every query runs in a read-only transaction (SQLSTATE 25006). The guard is advisory; the read-only transaction and the role's own privileges are what prevent writes.
`query_timeout`	The statement ran past its deadline and was stopped. The deadline is `timeoutMs`, or `SEZZLEE_POSTGRES_QUERY_TIMEOUT_MS` when the call does not set one.
`query_cancelled`	The call was cancelled, by the client or because the call ended, before the statement finished, or another session cancelled the statement.
`query_failed`	PostgreSQL reported an error this server has no more specific code for, most often a syntax error, a function that does not exist, or a value that does not convert. The message carries the engine's text and its SQLSTATE in parentheses.
`object_not_found`	The table, view or column does not exist, or the role cannot see it. A table name without its schema is looked up only in `pg_catalog`, so write `schema.table`. Names come from `search_catalog`.
`permission_denied`	PostgreSQL refused the statement because the role lacks a privilege: `SELECT` on a table, `USAGE` on a schema, or `CONNECT` on the database.
`deadlock`	PostgreSQL chose this statement as the victim of a deadlock. Retrying the same call usually succeeds.
`unsupported_type`	Not raised by this server. A column whose type has no JSON form is returned with `kind: "unknown"` instead of failing the call.

Server

Code	Meaning
`internal_error`	A defect in the server, not in your database or your call. This is the one code with no `recovery`, because there is no next call that fixes it. The detail is written to the server's stderr.