GraphQL errors
Which error answers which envelope — an async-graphql Error, a ToProblem, a ServiceError — and what a client is never owed.
A resolver returns T or a Result<T, E>; an Err short-circuits with a
GraphQL error envelope alongside data. Which envelope is decided by the
error’s type, so a client reads only what someone meant it to read:
- an
async_graphql::Erroryou built is answered as built; - an error implementing
ToProblemanswers the problem it says — its sentence and a stableextensions.code, with its problem type’sextensions.typeandextensions.titleand its field map’sextensions.errorswhen it has them; - the framework’s own vocabulary found in the chain — a
Problem, a pipe rejection, a decode failure said without its value — answers in its own form; - anything else answers
"internal error"under theINTERNALcode, and its whole chain is filed once aterroronnest_rs::graphql.
A return is fallible when it is spelled the way async-graphql reads one —
Result<T, E> or FieldResult<T> — and anything else is a value: a payload
named SearchResult is an object. The message goes on errors[].message;
structured data goes on errors[].extensions. The framework’s shared error
type, ServiceError from nest-rs-seaorm, implements ToProblem, so a feature
returns its service result and the wire shape just works.
The smallest error
Section titled “The smallest error”use nest_rs::graphql::async_graphql::{Error, Result};use nest_rs::graphql::{operations, resolver};
#[resolver]pub struct PostsResolver;
#[operations]impl PostsResolver { #[query] #[public] async fn post(&self, id: String) -> Result<String> { if id.is_empty() { return Err(Error::new("id must not be empty")); } Ok(format!("post {id}")) }}On the wire:
{ "data": null, "errors": [ { "message": "id must not be empty", "path": ["post"], "locations": [{ "line": 1, "column": 3 }] } ]}Error::new is the deliberate spelling: a ? that would turn a foreign error
into an async_graphql::Error does not compile, because async-graphql’s
custom-error-conversion is on — the blanket conversion would ship the error’s
Display before the framework could answer it opaquely. Return the error itself
(Result<T, MyError>) and let its type decide.
The framework rewrites every message that quotes a value the request carried.
A decode failure: serde’s sentence quotes the value it refused — a resolver
returning a serde_json error, or an anyhow chain holding one, async-graphql’s
own Json<T> scalar coercing an argument — so errors[].message says where and
what kind instead: invalid type: a string, expected u64 at line 1 column 24,
under the INVALID_ARGUMENT code. A value from variables, or written in the
document, that its argument’s type refuses: async-graphql quotes it, and the
message says it by kind — enumeration type "Role" does not contain the value sent, an unknown field of type "PostFilter", Expected input type "Int", found a string., and a scalar’s own refusal as Failed to parse "UUID": a value its type does not accept. And an operationName the document holds no
operation of: the request’s operationName is any text the client wrote, so
the message reads Unknown operation named by operationName. And a document
that does not parse: the parser renders the line it stopped on, whatever that
line holds, so the message says where it stopped and what the grammar expected
there — Syntax error at line 1 column 46: expected name, locations naming the
same place. Every rewrite holds on the socket as on POST. A name the document
spells — a field, an argument, a fragment, a variable — stays in the message,
as the GraphQL specification’s own errors name it; it is the sender’s own
document, and no log line carries it.
Extensions and codes
Section titled “Extensions and codes”extensions.code is the stable class a client branches on without parsing the
message, read off nest_rs::core::code, and a feature’s own error says its class
through ToProblem once for every edge. GraphQL error
codes lists the codes, a problem’s type and title, and the
field map keyed by the schema’s names.
ServiceError
Section titled “ServiceError”A service method the feature writes returns Result<T, ServiceError> — a
CrudService read answers a RepoError, which converts into no edge’s error, so the
method’s ? makes it a ServiceError — and ServiceError implements ToProblem: NotFound answers NOT_FOUND, Conflict CONFLICT,
Forbidden FORBIDDEN, Invalid and Validation INVALID_ARGUMENT, each with
its own sentence, a validation failure’s fields under extensions.errors; Db and Internal answer opaquely, their cause
filed at error — but for a statement Postgres cancelled at its bound, a Db answering
"service unavailable" under UNAVAILABLE, with its retryAfterSeconds when the bound
gives one, its cause at warn. A resolver returns such a method’s result as it is:
use nest_rs::authz::Read;use nest_rs::graphql::{operations, resolver};use nest_rs::seaorm::ServiceError;
#[operations]impl PostsResolver { #[query] #[authorize(Read, posts::Entity)] async fn post(&self, id: String) -> Result<Post, ServiceError> { self.svc.find_by_id(&id).await }}A RepoError turned into a ServiceError by ? keeps its class: a unique
violation becomes Conflict, a write the caller’s grants do not cover
Forbidden, a row a write found gone NotFound, any other failure Db, filed
by its SQLSTATE, never by the server’s message. A #[crud] operation answers the same classes, a create
or an update a unique key refuses naming the input’s fields that key holds
under extensions.errors
(When the database refuses), and a
mutation field answering one rolls back its own writes — the whole operation’s,
when its null reaches data
(GraphQL: one unit per operation).
A body that mixes failures keeps async_graphql::Result and uses ?:
ServiceError converts into async_graphql::Error through the same
ToProblem, the one conversion nest-rs-seaorm writes for it.
An error the client is not owed
Section titled “An error the client is not owed”An error with no ToProblem is already answered opaquely. Opaque says so at
the call site, where a failure the client could otherwise read is one it must
not — and it reads the same on every client-facing transport, HTTP, GraphQL,
WebSockets and MCP:
use nest_rs::graphql::Opaque;
#[query]#[authorize(Read, posts::Entity)]async fn post(&self, id: String) -> nest_rs::graphql::async_graphql::Result<Post> { Ok(self.svc.find_by_id(&id).await.opaque()?)}.opaque()? puts a constant message on the wire, under the same INTERNAL
code an internal denial carries — so a client cannot tell an unexpected
failure from a refusal it was owed no explanation for — and keeps the real
error for the operator. It is filed at error on nest_rs::graphql once the
answer is final, naming the root field it was met under by kind and field:
where the root field’s site answers, or a #[field_resolver]’s, and, for an
object resolver written by hand, where its operation or a subscription’s item
answers — or ends unanswered, cut at the request’s deadline or stopped first.
An exception filter answering the failure with a 4xx leaves no line;
problem_error keeps a 5xx problem’s chain the same way.
An exception filter answers first
Section titled “An exception filter answers first”Every rule above is what a field answers when nothing answered it. An
exception filter bound
on the resolver — #[use_exception_filters] on the #[resolver] struct or
beside a root field — or on the app reads the failure before them. A field has
no reply a filter writes through a view, so one claiming the error’s type
answers with a Problem, which the field renders in this page’s form — its
sentence on message, its code on extensions.code — while the operation’s
other fields resolve as they would:
#[async_trait]impl ExceptionFilter for LedgerConflict { type Exception = LedgerRefused;
async fn catch(&self, _: &LedgerRefused, _: &mut UnitContext<'_>) -> Caught { Caught::Problem(Problem::new(409, code::CONFLICT).with_detail("the ledger is busy")) }}A #[field_resolver] runs only the filters declared on it. The chain behind a
5xx the filter answers is filed as for any other; one it answers 4xx files
nothing. A field that failed stays failed, so a mutation field’s savepoint rolls
back whatever the filter answered.
Authorization denials
Section titled “Authorization denials”A guard’s denial reads the same on every edge. On GraphQL it answers its
sentence under its code — UNAUTHENTICATED, FORBIDDEN, INSUFFICIENT_SCOPE
with requiredScopes, RATE_LIMITED with retryAfterSeconds — and a server
side failure never carries the guard’s text: an unavailable dependency answers
"service unavailable" under UNAVAILABLE (with retryAfterSeconds when
known), an internal denial "internal error" under INTERNAL.
The handler doesn’t write the mapping; it just declares
#[authorize(Action, Entity)]. See Security for
the full chain.
Partial results
Section titled “Partial results”A field that fails answers null beside its siblings’ answers, up to the nearest
nullable field: Option<T> is the return for an absent value, an error for an
abnormal one. Partial results is where the null
lands and every error one response carries.
A body that is not a GraphQL request
Section titled “A body that is not a GraphQL request”A body that is JSON but not a request — "variables" as a string — or not
JSON at all is refused before anything executes: 400, and one errors entry
saying why, the way GraphQL-over-HTTP answers a request it cannot accept. No
data member, since nothing ran. The why is a decode failure, said like every
edge says one — where and of what kind, never the value sent, under
INVALID_ARGUMENT:
$ curl -s localhost:3000/graphql -H 'content-type: application/json' \ -d '{"query":"{ tag }","variables":"sk_live_secret"}'{"errors":[{"message":"the body is not a GraphQL request: the JSON body at `variables`: invalid type: a string, expected a map","extensions":{"code":"INVALID_ARGUMENT"}}]}Going further
Section titled “Going further”- Queries and mutations — the
Result<T>return shape at the top level. - Security — the guard chain that decides
UNAUTHENTICATED/FORBIDDENbefore a resolver runs. - Database — the service contract behind these errors.