Pothos v4 is now available! 🎉Check out the full migration guide here



Common problems and troubleshooting steps.

This document is currently very incomplete, if you run into issues and find a useful solution, please feel free to add any tips here

Type issues

  1. Ensure that typescript is using strict mode

  2. Move your builder types to a separate named interface

    • This will make many type errors significantly more readable
interface PothosTypes {
  Context: {
    user: {
      id: string;
const builder = new SchemaBuilder<PothosTypes>({...});

Slow vscode or typescript performance

  1. Ensure you are not including any very complex objects in your Context type. See https://github.com/microsoft/TypeScript/issues/45405

Runtime issues

Plugin methods are not defined

Ensure that there is only 1 version of each pothos package, and that they are both in the same root node_modules directly. Pothos plugins import classes from @pothos/core to add plugin specific methods to the class prototypes

Recieved multiple implementations for plugin

By default, Pothos doesn't allow multiple plugin registrations with the same name. During development, it can be helpful to disable this check by setting SchemaBuilder.allowPluginReRegistration = true.

Keep in mind that this not only allows plugins to be updated when for example, using HMR but can also lead to unexpected behavior with plugins using the same name.

Refs is undefined

If you are running into issues with refs being undefined, it may be due to a circular import. Most circular imports will work correctly with pothos as long as the following conditions are true:

  1. The builder is defined in a file that does not import any files that use the builder (or indirectly import it).
  2. builder.toSchema() is called in a file that is not imported by any files that use the builder.

This is generally done by having a simple builder.ts that initializes the builder to export. This file can also define some core parts of your schema (the query object, scalers etc). The rest of the schema can then import the builder from builder.ts. A schema.ts file can then import all files that define parts of the schema. schema.ts can then call builder.toSchema() and export the result for use by the server.

On this page