5 GraphQL Resolver Best Practices (DataLoader, Error Handling)

I've reviewed a lot of GraphQL APIs over the years, and the pattern I see most often isn't wrong syntax or incorrect schema design — it's resolvers that are technically correct but silently destroying database performance. A hundred-line resolver that makes 300 database queries for a single request is "working" right up until it isn't.

These five practices cover the things that actually matter for production GraphQL resolvers: fixing the N+1 problem, handling errors without leaking internals, keeping authentication clean, and structuring resolvers for maintainability.

Why Resolver Quality Matters More Than Schema Design

Your GraphQL schema can be beautifully designed — clean types, sensible relationships, good naming. But if the resolvers are naive, you're handing every client a loaded foot-gun. Clients can request deeply nested data, and each level of nesting can multiply your database queries.

GraphQL's flexibility is its strength and its trap. A query like this looks innocent:

query {
  posts(limit: 50) {
    title
    author {
      name
      avatar
    }
    comments(limit: 5) {
      text
      commenter {
        name
      }
    }
  }
}

With naive resolvers, this single query against a dataset of 50 posts with 5 comments each fires: 1 (posts) + 50 (authors) + 50 (comments pages) + 250 (commenters) = 351 database queries. For one page load.

The five practices below prevent this — and the other ways resolvers go wrong.

Practice 1: Fix the N+1 Problem with DataLoader

DataLoader is the standard solution to the N+1 problem in GraphQL. It works by batching and caching per-request. Instead of calling the database once for each item, it collects all the IDs requested in the current tick and makes a single batched query.

Install it:

npm install dataloader

Create your DataLoaders in the context function — one per request, so the cache doesn't bleed between requests:

// context.js
const DataLoader = require('dataloader');
const { getUsersByIds, getCommentsByPostIds } = require('./db/queries');

function createLoaders() {
  return {
    // Batch load users by IDs
    userLoader: new DataLoader(async (userIds) => {
      // userIds is an array of all IDs requested in this batch
      const users = await getUsersByIds(userIds);
      
      // DataLoader requires results in the SAME ORDER as input IDs
      const userMap = users.reduce((map, user) => {
        map[user.id] = user;
        return map;
      }, {});
      
      return userIds.map(id => userMap[id] || null);
    }),

    // Batch load comments by post IDs
    commentsByPostLoader: new DataLoader(async (postIds) => {
      const comments = await getCommentsByPostIds(postIds);
      
      // Group comments by postId
      const commentsByPost = postIds.map(postId =>
        comments.filter(c => c.postId === postId)
      );
      
      return commentsByPost;
    })
  };
}

// Apollo Server context
const context = ({ req }) => {
  const token = req.headers.authorization?.split(' ')[1];
  const user = token ? verifyToken(token) : null;
  
  return {
    user,
    loaders: createLoaders()  // Fresh loaders per request
  };
};

The corresponding database queries (using pg directly, but the pattern applies to any ORM):

// db/queries.js
const pool = require('./pool');

async function getUsersByIds(ids) {
  const result = await pool.query(
    'SELECT * FROM users WHERE id = ANY($1::int[])',
    [ids]
  );
  return result.rows;
}

async function getCommentsByPostIds(postIds) {
  const result = await pool.query(
    'SELECT * FROM comments WHERE post_id = ANY($1::int[])',
    [postIds]
  );
  return result.rows;
}

Now in your resolvers, use the loader instead of a direct DB call:

// resolvers.js
const resolvers = {
  Query: {
    posts: async (_, { limit = 10 }, { user }) => {
      // Top-level queries can query directly — no N+1 risk here
      return db.query('SELECT * FROM posts LIMIT $1', [limit]);
    }
  },
  
  Post: {
    // This resolver fires once per post in the result set
    // WITHOUT DataLoader: 1 DB query per post
    // WITH DataLoader: 1 batched query for all posts
    author: async (post, _, { loaders }) => {
      return loaders.userLoader.load(post.authorId);
    },
    
    comments: async (post, { limit = 10 }, { loaders }) => {
      const comments = await loaders.commentsByPostLoader.load(post.id);
      return comments.slice(0, limit);
    }
  },
  
  Comment: {
    commenter: async (comment, _, { loaders }) => {
      return loaders.userLoader.load(comment.userId);
    }
  }
};

The userLoader is shared across Post.author and Comment.commenter. If 50 posts all have the same author, DataLoader deduplicates — one cache hit, zero extra queries.

The result: that 351-query example becomes 4 queries total. For more context on how this fits into the broader REST vs GraphQL trade-off, see GraphQL vs REST performance.

Practice 2: Error Handling Without Leaking Internals

Default GraphQL error handling is not safe for production. By default, errors propagate to the client with full stack traces and internal details.

There are two types of errors in a GraphQL API:

1. Expected errors (user doesn't exist, wrong password, permission denied) — these should be clear, client-actionable messages
2. Unexpected errors (database connection failed, null pointer) — these should be generic to the client but logged in detail server-side

const { ApolloError, UserInputError, AuthenticationError, ForbiddenError } = require('apollo-server-express');

const resolvers = {
  Mutation: {
    createPost: async (_, { input }, { user }) => {
      // Auth check first
      if (!user) {
        throw new AuthenticationError('You must be signed in to create a post');
      }
      
      // Input validation
      if (!input.title || input.title.trim().length < 3) {
        throw new UserInputError('Title must be at least 3 characters', {
          field: 'title'
        });
      }
      
      try {
        const post = await db.createPost({ ...input, authorId: user.id });
        return post;
      } catch (err) {
        // Log the real error server-side
        console.error('Failed to create post:', err);
        
        // Send a generic message to the client
        throw new ApolloError('Failed to create post. Please try again.', 'INTERNAL_ERROR');
      }
    }
  }
};

For Apollo Server 4+, configure error formatting globally:

const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (formattedError, error) => {
    // Log unexpected errors
    if (!formattedError.extensions?.code || 
        formattedError.extensions.code === 'INTERNAL_SERVER_ERROR') {
      console.error('Unexpected GraphQL error:', error);
    }
    
    // Never expose stack traces in production
    if (process.env.NODE_ENV === 'production') {
      const { stacktrace, ...safeExtensions } = formattedError.extensions || {};
      return { ...formattedError, extensions: safeExtensions };
    }
    
    return formattedError;
  }
});

This pattern ensures clients get useful error messages for expected failures, and generic messages for everything else — while your logs capture the full details.

Practice 3: Authentication and Authorization in Context

Authentication logic does not belong in individual resolvers. If you're checking JWT tokens inside 20 different resolvers, you have 20 places to get it wrong and 20 places to update when your auth logic changes.

Authentication belongs in the context function:

const jwt = require('jsonwebtoken');

const context = async ({ req }) => {
  const token = req.headers.authorization?.replace('Bearer ', '');
  
  let user = null;
  if (token) {
    try {
      const decoded = jwt.verify(token, process.env.JWT_SECRET);
      // Optionally load fresh user data from DB
      user = await userLoader.load(decoded.userId);
    } catch (err) {
      // Invalid token — context.user stays null
      // Don't throw here; let resolvers decide if auth is required
    }
  }
  
  return {
    user,
    loaders: createLoaders()
  };
};

Authorization — checking what a specific authenticated user can do — belongs inside each resolver:

const resolvers = {
  Mutation: {
    deletePost: async (_, { id }, { user }) => {
      if (!user) throw new AuthenticationError('Sign in required');
      
      const post = await db.getPostById(id);
      if (!post) throw new UserInputError('Post not found');
      
      // Check ownership OR admin role
      if (post.authorId !== user.id && user.role !== 'admin') {
        throw new ForbiddenError('You can only delete your own posts');
      }
      
      await db.deletePost(id);
      return true;
    }
  }
};

This separation means you can test authorization logic in isolation, the context function stays focused on one job, and resolvers that don't require auth are clean.

For a deeper look at authentication patterns including JWT, OAuth, and API keys, API authentication guide covers the full spectrum.

Practice 4: Resolver Composition and Keeping Resolvers Thin

A common anti-pattern is resolvers that do everything: query the DB, transform data, validate business rules, send emails, call external APIs. When a resolver is 200 lines, something has gone wrong.

Good resolvers are thin. They delegate:

// BAD: resolver doing everything
const resolvers = {
  Mutation: {
    registerUser: async (_, { email, password }) => {
      // Input validation
      if (!email.includes('@')) throw new Error('Invalid email');
      if (password.length < 8) throw new Error('Password too short');
      
      // Check if exists
      const existing = await pool.query('SELECT id FROM users WHERE email = $1', [email]);
      if (existing.rows.length) throw new Error('Email already registered');
      
      // Hash password
      const hash = await bcrypt.hash(password, 12);
      
      // Insert user
      const result = await pool.query(
        'INSERT INTO users (email, password_hash) VALUES ($1, $2) RETURNING *',
        [email, hash]
      );
      
      // Send welcome email
      await sendEmail({ to: email, subject: 'Welcome!' });
      
      // Generate JWT
      return { token: jwt.sign({ userId: result.rows[0].id }, process.env.JWT_SECRET) };
    }
  }
};

// GOOD: resolver delegates to a service
const resolvers = {
  Mutation: {
    registerUser: async (_, { email, password }) => {
      return authService.registerUser({ email, password });
    }
  }
};

The authService contains the same logic, but now it's:

• Independently testable without a GraphQL setup
• Reusable (REST endpoint, CLI script, background job)
• Independently readable

This connects to the REST vs GraphQL discussion in REST vs GraphQL guide — thin resolvers make it easier to support both if you ever need to.

Practice 5: Resolver Performance Measurement

You can't optimize what you don't measure. Before declaring your resolvers "fast enough," instrument them.

Apollo Studio provides resolver-level tracing, but you can add lightweight instrumentation manually:

// Wrap resolvers with timing
function withTiming(resolverName, resolver) {
  return async (parent, args, context, info) => {
    const start = Date.now();
    try {
      const result = await resolver(parent, args, context, info);
      const duration = Date.now() - start;
      
      if (duration > 100) {
        console.warn(`Slow resolver: ${resolverName} took ${duration}ms`);
      }
      
      return result;
    } catch (err) {
      const duration = Date.now() - start;
      console.error(`Resolver error: ${resolverName} failed after ${duration}ms`, err);
      throw err;
    }
  };
}

// Apply to your resolvers
const resolvers = {
  Query: {
    posts: withTiming('Query.posts', async (_, { limit }) => {
      return db.getPosts(limit);
    })
  }
};

For production, use Apollo Studio's trace reporting or integrate with your existing observability stack. The key metrics to track: p50 and p99 resolver duration, and a count of DataLoader cache hits vs misses (high miss rate means your batching isn't working as expected).

Resolver Approach Comparison

The Prisma ORM PostgreSQL post covers how ORMs relate to this — Prisma has its own query batching that partially addresses N+1 for certain patterns, though DataLoader is still the right tool for GraphQL.

For API performance benchmarks comparing GraphQL to REST under load, see GraphQL vs REST performance.

Conclusion

Five practices, one goal: resolvers that work correctly under production load and don't turn into debugging nightmares at 3 AM. The DataLoader fix for N+1 is non-negotiable for any GraphQL API serving list data. Everything else — structured error handling, auth in context, thin resolvers, and performance measurement — is the difference between a prototype and a production system.

The good news: none of this is complicated. DataLoader is 50 lines of setup. Clean error handling is a one-time config. Thin resolvers are a habit, not a library. Start with DataLoader and structured errors, then layer in the rest.

Your database server will thank you.

Frequently Asked Questions

What is the N+1 problem in GraphQL and why does it matter?

The N+1 problem occurs when a resolver fetches a list of N items, then makes one additional database query for each item to fetch related data — resulting in N+1 total queries instead of just 2. For example, fetching 100 posts with their authors triggers 100 separate user queries. At small scale this is annoying; at production scale it can take a server down. DataLoader solves this by batching all those individual lookups into a single query per request.

Should I use DataLoader for every resolver or only specific ones?

Use DataLoader specifically for resolvers that load a single record by ID inside a list — the classic N+1 pattern. You don't need it for top-level queries that already fetch everything in one go (e.g., a posts resolver that does SELECT * FROM posts). The signal that you need DataLoader: your resolver receives an individual parent object and needs to fetch a related entity. If you're fetching by ID inside a resolver that's called repeatedly, DataLoader belongs there.

How do I handle authentication and authorization in GraphQL resolvers?

Authentication (who is this user?) belongs in the context function — called once per request before any resolver runs. Verify the JWT or session token there and attach the user to context. Authorization (can this user do this thing?) belongs inside the resolver itself, not the context. Check context.user.role or context.user.id at the start of each resolver that requires it. For fine-grained permissions, directive-based auth (using graphql-shield or custom schema directives) is cleaner than manual if-checks in every resolver.