Skip to content

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::Error you built is answered as built;
  • an error implementing ToProblem answers the problem it says — its sentence and a stable extensions.code, with its problem type’s extensions.type and extensions.title and its field map’s extensions.errors when 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 the INTERNAL code, and its whole chain is filed once at error on nest_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.

crates/features/src/posts/graphql/resolver.rs
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.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.

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:

crates/features/src/posts/graphql/resolver.rs
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 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:

crates/features/src/posts/graphql/resolver.rs
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.

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:

crates/features/src/orders/graphql/exception_filter.rs
#[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.

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.

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 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:

Terminal window
$ 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"}}]}
  • Queries and mutations — the Result<T> return shape at the top level.
  • Security — the guard chain that decides UNAUTHENTICATED / FORBIDDEN before a resolver runs.
  • Database — the service contract behind these errors.