Error codes

Generated from the error-code union types of @sezzlee/mssql-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 SQL Server is listening:

json

{
  "content": [
    {
      "type": "text",
      "text": "{\"error\":\"connection_failed\",\"message\":\"Failed to connect to 127.0.0.1:1433 - Could not connect (sequence) (ESOCKET)\",\"recovery\":\"The database was not reachable; retrying may succeed once it is.\"}"
    }
  ],
  "isError": true
}

The text item, parsed:

json

{
  "error": "connection_failed",
  "message": "Failed to connect to 127.0.0.1:1433 - Could not connect (sequence) (ESOCKET)",
  "recovery": "The database was not reachable; retrying may succeed once it is."
}

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, or a statement SQL Server refuses to compile: a syntax error, an unknown column, or a function that does not exist. The message carries the engine's own text and error number. For an undeclared or mistyped argument the recovery lists the arguments the tool accepts.
`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, an encryption setting the server does not accept, or no answer within the connect timeout.
`authentication_failed`	SQL Server refused the login. Check `SEZZLEE_MSSQL_USER`, `SEZZLEE_MSSQL_PASSWORD` and that the login may open `SEZZLEE_MSSQL_DATABASE`.
`database_unavailable`	SQL Server refused to open the configured database (error 4060): it does not exist, or the login has no access to it. Check `SEZZLEE_MSSQL_DATABASE` and that the login has a user in that database.

Queries

Code	Meaning
`write_not_permitted`	No query ran. Either the connected login can write to or administer the database, or its privileges could not be verified: `run_query` answers only for a read-only login, 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, carries a keyword that starts another statement or reaches outside the database, draws `NEXT VALUE FOR` a sequence, names a system procedure, or contains a control or invisible character. The guard is advisory; the login's own permissions are what prevent writes.
`query_timeout`	The statement ran past its deadline and was cancelled. The deadline is `timeoutMs`, or `SEZZLEE_MSSQL_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.
`query_failed`	SQL Server reported an error this server has no more specific code for. The message carries the engine's text and error number.
`object_not_found`	The table or view does not exist, or the login cannot see it. Names come from `search_catalog`.
`permission_denied`	SQL Server refused the statement because the login lacks a permission on an object it reads.
`deadlock`	SQL Server 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.