---
title: Errors plugin
description: Errors plugin docs for Pothos
---
Represent expected failures as GraphQL result unions. Register error classes as object types, then
list them in a field's `errors` option. The plugin catches matching errors and returns an error
object that clients can query with fragments. Errors that do not match still become GraphQL errors.
## Usage
### Install
```package-install
npm install --save @pothos/plugin-errors
```
### Example Usage
```typescript
import SchemaBuilder from '@pothos/core';
import ErrorsPlugin from '@pothos/plugin-errors';
const builder = new SchemaBuilder({
plugins: [ErrorsPlugin],
errors: {
defaultTypes: [],
// onResolvedError: (error) => console.error('Handled error:', error),
},
});
builder.objectType(Error, {
name: 'Error',
fields: (t) => ({
message: t.exposeString('message'),
}),
});
builder.queryType({
fields: (t) => ({
hello: t.string({
errors: {
types: [Error],
},
args: {
name: t.arg.string({ required: false }),
},
resolve: (parent, { name }) => {
if (name && name.slice(0, 1) !== name.slice(0, 1).toUpperCase()) {
throw new Error('name must be capitalized');
}
return `hello, ${name || 'World'}`;
},
}),
}),
});
```
The above example will produce a GraphQL schema that looks like:
```graphql
type Error {
message: String!
}
type Query {
hello(name: String): QueryHelloResult
}
union QueryHelloResult = Error | QueryHelloSuccess
type QueryHelloSuccess {
data: String!
}
```
This field can be queried using fragments like:
```graphql
query {
hello(name: "World") {
__typename
... on Error {
message
}
... on QueryHelloSuccess {
data
}
}
}
```
This plugin works by wrapping fields that define error options in a union type. This union consists
of an object type for each error type defined for the field, and a Success object type that wraps
the returned data. If the fields resolver throws an instance of one of the defined errors, the
errors plugin will automatically resolve to the corresponding error object type.
### Expected and unexpected errors
Only errors matching a field's registered classes become typed results. With the imports and
builder setup above, this alternative query definition catches `NameTooShort` and exposes its
`message` and `minimum` fields. Successful greetings use `QueryGreetingSuccess`; a plain `Error`
remains a GraphQL error because this field does not register that class.
playground-examples/plugin-errors/schema.ts#error,field
### Builder options
- `defaultTypes`: An array of Error classes to include in every field with error handling.
- `directResult`: Sets the default for `directResult` option on fields (only affects non-list
fields)
- `onResolvedError`: A callback function that is called when an error is handled by the plugin
- `defaultResultOptions`: Defaults for generated success object types.
- `defaultUnionOptions`: Defaults for generated result union types.
- `defaultItemResultOptions`: Defaults for per-item success object types.
- `defaultItemUnionOptions`: Defaults for per-item result union types.
- `unsafelyHandleInputErrors`: Also catch input mapping and validation errors; see
[With validation plugin](#with-validation-plugin).
The four type-options objects accept a `name` function receiving `{ parentTypeName, fieldName }`.
Use distinct names for success objects and unions:
```typescript
const builder = new SchemaBuilder({
plugins: [ErrorsPlugin],
errors: {
defaultTypes: [Error],
defaultResultOptions: {
name: ({ parentTypeName, fieldName }) => `${parentTypeName}_${fieldName}_Success`,
},
defaultUnionOptions: {
name: ({ parentTypeName, fieldName }) => `${parentTypeName}_${fieldName}_Result`,
},
},
});
```
### Options on Fields
- `types`: An array of Error classes to catch and handle as error objects in the schema. Will be
merged with `defaultTypes` from builder.
- `union`: An options object for the union type. Can include any normal union type options, and
`name` option for setting a custom name for the union type.
- `result`: An options object for result object type. Can include any normal object type options,
and `name` option for setting a custom name for the result type.
- `dataField`: An options object for the data field on the result object. This field will be named
`data` by default, but can be renamed by passing a custom `name` option.
- `directResult`: Boolean, can only be set to true for non-list fields. This will directly include
the fields type in the union rather than creating an intermediate Result object type. This will
throw at build time if the type is not an object type.
### A shared Error interface
1. Set up an Error interface
2. Create a BaseError object type
3. Include the Error interface in any custom Error types you define
4. Include the BaseError type in the `defaultTypes` in the builder config
This pattern will allow you to consistently query your schema using a `... on Error { message }`
fragment since all Error classes extend that interface. If your client wants to query details of
more specialized error types, they can just add a fragment for the errors it cares about. This
pattern should also make it easier to make future changes without unexpected breaking changes for
your clients.
This is a separate setup from the first example:
```typescript
import SchemaBuilder from '@pothos/core';
import ErrorsPlugin from '@pothos/plugin-errors';
const builder = new SchemaBuilder({
plugins: [ErrorsPlugin],
errors: {
defaultTypes: [Error],
},
});
const ErrorInterface = builder.interfaceRef('Error').implement({
fields: (t) => ({
message: t.exposeString('message'),
}),
});
builder.objectType(Error, {
name: 'BaseError',
interfaces: [ErrorInterface],
});
class LengthError extends Error {
minLength: number;
constructor(minLength: number) {
super(`string length should be at least ${minLength}`);
this.minLength = minLength;
this.name = 'LengthError';
}
}
builder.objectType(LengthError, {
name: 'LengthError',
interfaces: [ErrorInterface],
fields: (t) => ({
minLength: t.exposeInt('minLength'),
}),
});
builder.queryType({
fields: (t) => ({
// Simple error handling just using base error class
hello: t.string({
errors: {},
args: {
name: t.arg.string({ required: true }),
},
resolve: (parent, { name }) => {
if (!name.startsWith(name.slice(0, 1).toUpperCase())) {
throw new Error('name must be capitalized');
}
return `hello, ${name || 'World'}`;
},
}),
// Handling custom errors
helloWithMinLength: t.string({
errors: {
types: [LengthError],
},
args: {
name: t.arg.string({ required: true }),
},
resolve: (parent, { name }) => {
if (name.length < 5) {
throw new LengthError(5);
}
return `hello, ${name || 'World'}`;
},
}),
}),
});
```
### With validation plugin
The validation plugin runs before field resolution. Set `unsafelyHandleInputErrors: true` to
return its failures as typed results. A validation failure then returns without running field
authorization hooks, so only enable this when those error details may be returned before authorization.
This standalone example registers the validation error and its issues. Valid input reaches the
resolver; invalid input returns `InputValidationError`.
```typescript
import SchemaBuilder from '@pothos/core';
import ErrorsPlugin from '@pothos/plugin-errors';
import ValidationPlugin, {
InputValidationError,
type StandardSchemaV1,
} from '@pothos/plugin-validation';
import { z } from 'zod';
const builder = new SchemaBuilder({
plugins: [ErrorsPlugin, ValidationPlugin],
errors: { unsafelyHandleInputErrors: true },
});
const InputValidationIssue = builder
.objectRef('InputValidationIssue')
.implement({
fields: (t) => ({
message: t.exposeString('message'),
path: t.stringList({
resolve: (issue) => issue.path?.map((part) =>
String(typeof part === 'object' ? part.key : part),
) ?? [],
}),
}),
});
builder.objectType(InputValidationError, {
name: 'InputValidationError',
fields: (t) => ({
issues: t.field({
type: [InputValidationIssue],
resolve: (err) => err.issues,
}),
}),
});
builder.queryType();
builder.queryField('fieldWithValidation', (t) =>
t.boolean({
errors: {
types: [InputValidationError],
},
args: {
string: t.arg.string({
required: true,
validate: z.string().min(3, 'Too short'),
}),
},
resolve: () => true,
}),
);
```
Example query:
```graphql
query {
fieldWithValidation(string: "a") {
__typename
... on QueryFieldWithValidationSuccess {
data
}
... on InputValidationError {
issues {
message
path
}
}
}
}
```
Validation also protects writes inside a mutation resolver. This alternative builder stores
accepted names and returns structured issues for invalid input without changing the stored data.
It uses the same imports as the validation example above and requires
`@pothos/plugin-validation` and `zod` alongside the errors plugin.
playground-examples/plugin-validation/schema.ts#setup,issues,mutation
### With the dataloader plugin
To use this in combination with the dataloader plugin, ensure that the errors plugin is listed
BEFORE the dataloader plugin in your plugin list.
If a field with `errors` returns a `loadableObject`, or `loadableNode` the errors plugin will now
catch errors thrown when loading ids returned by the `resolve` function.
For a list of loadable IDs, loading happens per item. A load failure is not a whole-field failure,
so the field's `errors` option does not catch it. Use explicit error unions when you need typed
results for individual loads; see [List item errors](#list-item-errors) for the separate
`itemErrors` handling of errors returned or thrown while iterating the resolver's list.
### With the prisma plugin
To use this in combination with the prisma plugin, ensure that the errors plugin is listed BEFORE
the prisma plugin in your plugin list. This will enable `errors` option to work correctly with any
field builder method from the prisma plugin.
`errors` can be configured for any field, but if there is an error pre-loading a relation the error
will always be surfaced at the field that executed the query. Because there are cases that fall back to
executing queries for relation fields, these fields may still have errors if the relation was not
pre-loaded. Detection of nested relations will continue to work if those relations use the `errors`
plugin
### List item errors
Use `itemErrors` on a list field to wrap each item in its own result union. It accepts the same
options as `errors`. The following addition to the shared Error interface example yields one success, then throws an error. The plugin returns that error as the final item:
```typescript
builder.queryField('listWithErrors', (t) =>
t.intList({
nullable: false,
itemErrors: {},
resolve: function* () {
yield 1;
throw new Error('Boom');
},
}),
);
```
```graphql
type Query {
listWithErrors: [QueryListWithErrorsItemResult!]!
}
union QueryListWithErrorsItemResult = BaseError | QueryListWithErrorsItemSuccess
type QueryListWithErrorsItemSuccess {
data: Int!
}
```
At runtime, `itemErrors` also handles returned error instances. If the resolver's ordinary return
type does not include errors, use an explicit error union for a list that mixes returned data and errors.
The plugin also wraps sync and async iterators. A yielded error becomes an error item; a thrown
error becomes the final item and closes the iterator. Async iterable execution requires an executor
that supports it, such as GraphQL 17.
Combine `errors: {}` with `itemErrors: {}` to handle a whole-field failure as well. The outer
`QueryListWithErrorsResult` union contains `BaseError` and `QueryListWithErrorsSuccess`; the latter's
`data` field contains the list of `QueryListWithErrorsItemResult` items.
For an async source, the same field can use an async generator. Replace its resolver with:
```typescript
resolve: async function* () {
yield 1;
throw new Error('The next item could not be loaded');
},
```
This requires an executor that supports async iterables. A thrown error ends the iterator;
use an explicit error union when the source needs to return an error item and continue.
To handle both a failure before the list is returned and a failure during iteration, replace
`listWithErrors` with:
```typescript
builder.queryField('listWithErrors', (t) =>
t.intList({
nullable: false,
errors: {},
itemErrors: {},
args: { failBeforeLoad: t.arg.boolean() },
resolve: (_parent, { failBeforeLoad }) => {
if (failBeforeLoad) throw new Error('Could not load the list');
return (function* () {
yield 1;
throw new Error('Could not load the next item');
})();
},
}),
);
```
The generated result types are:
```graphql
union QueryListWithErrorsResult = BaseError | QueryListWithErrorsSuccess
type QueryListWithErrorsSuccess {
data: [QueryListWithErrorsItemResult!]!
}
union QueryListWithErrorsItemResult = BaseError | QueryListWithErrorsItemSuccess
type QueryListWithErrorsItemSuccess {
data: Int!
}
```
### Custom error union fields
Use `t.errorUnionField` and `t.errorUnionListField` to directly specify all members of the returned union type,
including multiple success types and error types.
The following additions use the `Error` class registered as `BaseError` in the shared-interface
example. Each success shape has an `isTypeOf` check so Pothos can distinguish plain objects.
The resolver bodies simulate create and update outcomes to demonstrate the union branches;
replace them with your application's persistence logic.
```typescript
const CreateResult = builder.objectRef<{ id: string; created: boolean }>('CreateResult').implement({
isTypeOf: (obj) => typeof obj === 'object' && obj !== null && 'created' in obj,
fields: (t) => ({
id: t.exposeString('id'),
created: t.exposeBoolean('created'),
}),
});
const UpdateResult = builder.objectRef<{ id: string; updated: boolean }>('UpdateResult').implement({
isTypeOf: (obj) => typeof obj === 'object' && obj !== null && 'updated' in obj,
fields: (t) => ({
id: t.exposeString('id'),
updated: t.exposeBoolean('updated'),
}),
});
builder.mutationType({
fields: (t) => ({
modifyUser: t.errorUnionField({
types: [CreateResult, UpdateResult, Error],
args: {
id: t.arg.id({ required: true }),
name: t.arg.string({ required: true }),
create: t.arg.boolean({ required: true }),
},
resolve: (parent, { id, name, create }) => {
if (name.length < 3) return new Error('Name too short');
return create ? { id: String(id), created: true } : { id: String(id), updated: true };
},
}),
processUsers: t.errorUnionListField({
types: [CreateResult, UpdateResult, Error],
args: { ids: t.arg.idList({ required: true }) },
resolve: (parent, { ids }) => ids.map((id) =>
id === 'unknown' ? new Error('User not found') : { id: String(id), updated: true },
),
}),
}),
});
```
#### Type resolution
Union members use standard Pothos type resolution. Registering an error class with
`builder.objectType` provides an `instanceof` check. Plain object types can supply `isTypeOf`, as
above, or you can pass a custom `resolveType` in the field's `union` options. Error instances matched
by the plugin are resolved before that custom callback.
For example, this alternative field resolves its success branches explicitly using the
`CreateResult` and `UpdateResult` types above:
```typescript
builder.mutationField('previewUserChange', (t) =>
t.errorUnionField({
types: [CreateResult, UpdateResult, Error],
args: { create: t.arg.boolean({ required: true }) },
union: {
resolveType: (value) => 'created' in value ? 'CreateResult' : 'UpdateResult',
},
resolve: (_parent, { create }) =>
create ? { id: '1', created: true } : { id: '1', updated: true },
}),
);
```
Matched error instances use the plugin's error map, so this callback only needs to distinguish
the success values.
### Using `builder.errorUnion`
You can use `builder.errorUnion` to manually construct an error union type that can be used with any field. Fields returning an error union will automatically handle returned or thrown errors.
This addition to the shared-interface example distinguishes a missing user from invalid input.
Both error types implement the shared `Error` interface, and validation failures expose the field
that needs correction:
```typescript
class NotFoundError extends Error {}
class ValidationError extends Error {
constructor(message: string, public field: string) {
super(message);
}
}
builder.objectType(NotFoundError, {
name: 'NotFoundError',
interfaces: [ErrorInterface],
});
builder.objectType(ValidationError, {
name: 'ValidationError',
interfaces: [ErrorInterface],
fields: (t) => ({ field: t.exposeString('field') }),
});
const User = builder.objectRef<{ id: string; name: string }>('User').implement({
isTypeOf: (obj) => typeof obj === 'object' && obj !== null && 'id' in obj && 'name' in obj,
fields: (t) => ({
id: t.exposeString('id'),
name: t.exposeString('name'),
}),
});
const UserResult = builder.errorUnion('UserResult', {
types: [User, NotFoundError, ValidationError],
});
builder.queryField('getUser', (t) =>
t.field({
type: UserResult,
args: { id: t.arg.string({ required: true }) },
resolve: (_, { id }) => {
if (!id) throw new ValidationError('ID required', 'id');
if (id === 'unknown') return new NotFoundError('User not found');
return { id, name: 'User' };
},
}),
);
```
Clients can select the common message or the details of a particular failure:
```graphql
query {
getUser(id: "") {
... on User {
id
name
}
... on Error {
message
}
... on ValidationError {
field
}
}
}
```
#### Options
- `types`: Array of member types (object refs, error classes, etc.)
- `omitDefaultTypes`: Set to `true` to exclude `defaultTypes` from the builder options (default: `false`)
- `resolveType`: Optional custom resolve function. Called after the internal error map check.
- All other standard union type options are supported