Error codes

Every message the AgensGraph server produces carries a five-character SQLSTATE code, exactly as PostgreSQL does. The first two characters name the error class, and the last three the specific condition within it. So an application that does not recognize a code can still act on its class.

AgensGraph defines no error codes of its own. Its error-code list is byte-identical to PostgreSQL 18’s, and a graph statement that fails raises one of PostgreSQL’s existing codes. The complete list of codes, with the condition name PL/pgSQL uses for each, is PostgreSQL’s Error Codes appendix. It is not reproduced here.

For a client, the practical consequence is that a graph-specific failure cannot be recognized by its code. multiple types for relationship not supported and Cypher query must end with RETURN, FINISH or update clause arrive as 0A000 and 42601. Those are the same codes an unsupported SQL feature and a SQL syntax error use. Match on the message text when you need to tell them apart, and treat the class as the reliable part.

Reading a code

Run \set VERBOSITY verbose in psql and every error afterwards carries its SQLSTATE and the source location that raised it:

\set VERBOSITY verbose

MATCH (m:movie {year: 1999}) WHERE m.title RETURN count(m);

ERROR:  42846: cannot cast "The Matrix" (jsonb type string) to boolean
LOCATION:  ExecEvalCypherTypeCast, execExprInterp.c:5900

Setting VERBOSITY to sqlstate prints the code alone. From a driver, the code is a field of the error object: sqlstate in most PostgreSQL clients.

Codes a graph statement commonly raises

These are the codes to expect from graph work, with a real message for each. The condition name is the one PL/pgSQL and most drivers use.

Code	Condition name	Raised by, for example
0A000	feature_not_supported	multiple types for relationship not supported — a relationship pattern with more than one type.
22023	invalid_parameter_value	labid out of range: 65536 — a graphid outside the range in Limits.
3F000	invalid_schema_name	graph_path is NULL — no working graph is set. A graph is a schema, which is why the class is this one.
42601	syntax_error	Cypher query must end with RETURN, FINISH or update clause, and every parse failure.
42703	undefined_column	variable does not exist — a name that is not in scope.
42712	duplicate_alias	WITH passes on "t" more than once, and the other name-collision refusals.
42846	cannot_coerce	cannot cast "…" (jsonb type string) to boolean — a condition given something other than a boolean.
42P07	duplicate_table	label "movie" already exists — a label is a table, so a duplicate label is a duplicate table.
54000	program_limit_exceeded	no more new labels are available — the label ids of a graph are exhausted.
55000	object_not_in_prerequisite_state	Vertex with connected edges cannot be removed — a DELETE that would leave a dangling edge.

Three of those rows show the pattern to expect. A graph is a schema, a label is a table, and a property is a jsonb value. So a graph error is reported in the class of the PostgreSQL object it is really about.

See also

• Cypher compatibility — the errors a query ported from another Cypher hits, with their text

• Limits — the two limits that produce 22023 and 54000

• Glossary — the terms these messages use