Error Categories And SQLSTATEs

pgContext uses stable error categories for SQL-visible failures. Error messages may become more specific, but clients should branch on SQLSTATE and documented category instead of parsing message text.

SQLSTATE compatibility is part of the stable SQL API. Changing the SQLSTATE for the same documented failure class is a breaking change unless the old path was experimental or internal.

Category SQLSTATE Meaning
InvalidVector 22P02 Malformed vector input
DimensionMismatch 22023 Valid input with incompatible dimensions
InvalidFilter 22023 Malformed or semantically invalid filter input
UnsafePredicate 22023 Rejected predicate rendering or unsafe path input
UnknownCollection 42704 Registered collection does not exist
UnknownVector 42704 Registered vector name does not exist
UnknownPayloadField 42703 Registered payload source column does not exist
UnknownTable 42P01 Referenced source table does not exist
WrongColumnType 42804 Referenced source column has an incompatible SQL type
DuplicateRegistration 42710 Collection, vector, payload, or model registration already exists
AclDenied 42501 PostgreSQL ACL, RLS, or ownership check denied access
IndexNotReady 55000 Index or artifact cannot currently serve queries
IndexCorrupt XX001 Index or artifact validation found corruption
RecallBudgetExceeded 54000 Search, recall-check, or candidate-recheck work exceeded a configured resource budget
UnsupportedMetric 0A000 Requested metric is not supported for this vector/index kind
UnsupportedPostgresVersion 0A000 PostgreSQL version is outside the supported matrix
Internal XX000 Unexpected internal invariant failure

Dense HNSW Boundary Errors

Dense HNSW preserves the vector categories above and adds PostgreSQL catalog validation where appropriate:

Failure SQLSTATE Message category
Non-finite text or values 22P02 InvalidVector
Dimension mismatch or invalid HNSW settings 22023 DimensionMismatch / invalid parameter
Forbidden vector representation cast 42846 Cannot coerce
Unsupported or internally inconsistent operator class 42P17 Invalid object definition
Stored metapage metric/configuration does not match the index XX001 IndexCorrupt

A NULL indexed vector is not an error: the access method stores no entry for that row. Cosine indexes reject zero-magnitude vectors with 22023 during build or insert because the selected metric is undefined for that value.