Mongoose findByIdAndUpdate() function: Tutorial & Examples

Updated: December 30, 2023 By: Guest Contributor Post a comment


Understanding how to update documents is crucial when working with MongoDB in a Node.js environment. Mongoose, a MongoDB object modeling tool, provides the findByIdAndUpdate() method, streamlining the update process. This tutorial discusses its usage and benefits with clear examples.

Getting Started

To use findByIdAndUpdate(), ensure Mongoose is connected to your MongoDB database:

import mongoose from 'mongoose';

Defining a Schema and Model

Before using findByIdAndUpdate(), you must have a Mongoose model:

import { Schema, model } from 'mongoose';
const userSchema = new Schema({
  name: String,
  age: Number,
  email: String
const User = model('User', userSchema);

Basic Example

The simplest use-case updates a user by ID without options:

const updateUser = async (userId, updateData) => {
  return await User.findByIdAndUpdate(userId, updateData);

Options and Their Effects

To customize behavior, pass options such as { new: true } to return the updated document:

const updateUserAndReturnNew = async (userId, updateData) => {
  return await User.findByIdAndUpdate(userId, updateData, { new: true });

Handling Errors

Always handle possible errors, especially when the ID is not found:

const updateUserSafely = async (userId, updateData) => {
  try {
    const updatedUser = await User.findByIdAndUpdate(userId, updateData, { new: true });
    return updatedUser || 'User not found.';
  } catch (error) {
    return error.message;

Advanced Usage

Updates with Validation

Activate validation with { runValidators: true }:

const updateUserWithValidation = async (userId, updateData) => {
  return await User.findByIdAndUpdate(
    { new: true, runValidators: true }

Conditional Updates

Include conditions within the update operation using query operators:

const conditionalUpdateUser = async (userId, updateData) => {
  return await User.findOneAndUpdate(
    { _id: userId, age: { $lt: 30 } },
    { new: true }

Using Update Operators

Use MongoDB update operators such as $inc to increment field values:

const incrementUserAge = async (userId) => {
  return await User.findByIdAndUpdate(
    { $inc: { age: 1 } },
    { new: true }


Mongoose’s findByIdAndUpdate() provides an efficient way to update documents. Always remember to handle conditions and validation to ensure data integrity. The transition from callbacks to modern async/await in Node.js enhances readability and error handling in your CRUD operations.