How to fix P2031: Prisma needs to perform transactions, which requires your MongoDB server to be run as a replica set in Prisma

PrismaINTERMEDIATEHIGHUpdated Dec 22, 2025· 124 views

This error occurs when Prisma attempts to use transactions on a standalone MongoDB instance. MongoDB requires replica sets for transaction support, which Prisma uses internally for nested writes and data consistency.

Quick fix

Fixes P2031: Prisma needs to perform transactions, which requires your MongoDB server to be run as a replica set

mongosh
  1. Verify your MongoDB configuration
  2. Stop your MongoDB instance
  3. Configure MongoDB as a replica set (Local Installation)
  4. Initialize the replica set
prisma — error
mongosh
P2031: Prisma needs to perform transactions, which requires your MongoDB server to be run as a replica set

What this error means

The P2031 error is a "MongoReplicaSetRequired" error that occurs when Prisma ORM tries to perform operations that require transactions on a MongoDB instance that is not configured as a replica set. MongoDB only allows transactions on replica sets, not on standalone MongoDB instances. Prisma uses transactions internally to support nested writes and avoid partial writes when creating or updating related documents. This means that even basic operations like creating a document with nested relationships require a replica set configuration. A MongoDB replica set is a group of MongoDB processes that maintain the same data set, providing redundancy and high availability. While replica sets are typically used with multiple nodes in production, you can configure a single-node replica set for local development, which gives you access to transactions and change streams while still running just one MongoDB instance.

Typical symptoms

  • Prisma operations fail with "P2031: Prisma needs to perform transactions" error message
  • Database queries work in MongoDB shell but fail through Prisma
  • Create or update operations with nested data fail immediately
  • Error appears when using prisma.model.create() or prisma.model.update() with relations
  • Application crashes during database initialization with Prisma

Common causes

  1. MongoDB is running as a standalone instance instead of a replica set
  2. MongoDB was installed locally without replica set configuration
  3. Docker container running MongoDB without --replSet flag
  4. Connection string missing replicaSet parameter
  5. MongoDB instance not initialized with rs.initiate() command

How to fix "P2031: Prisma needs to perform transactions, which requires your MongoDB server to be run as a replica set"

1Verify your MongoDB configuration

First, check if your MongoDB instance is running as a replica set. Connect to your MongoDB instance using mongosh:

bash
mongosh

Then run:

javascript
rs.status()

If you see an error like "no replset config has been received", your MongoDB is running in standalone mode and needs to be configured as a replica set.

2Stop your MongoDB instance

Before reconfiguring, stop your current MongoDB instance:

bash
# On Linux/macOS
sudo systemctl stop mongod

# Or if running manually
# Find the process and kill it
ps aux | grep mongod
kill <process-id>

If you're using Docker:

bash
docker stop <mongodb-container-name>
3Configure MongoDB as a replica set (Local Installation)

If you installed MongoDB locally, edit your MongoDB configuration file:

bash
# Linux: /etc/mongod.conf
# macOS (Homebrew): /usr/local/etc/mongod.conf
# Windows: C:\Program Files\MongoDB\Server\{version}\bin\mongod.cfg

Add or modify the replication section:

yaml
replication:
  replSetName: "rs0"

Then restart MongoDB:

bash
sudo systemctl start mongod
4Initialize the replica set

After starting MongoDB with replica set configuration, connect with mongosh and initialize the replica set:

bash
mongosh

Run the initialization command:

javascript
rs.initiate({
  _id: "rs0",
  members: [
    { _id: 0, host: "localhost:27017" }
  ]
})

You should see a response like:

json
{ "ok": 1 }

Your mongosh prompt should change to show you're now in a replica set (e.g., rs0 [direct: primary]).

5Update your Prisma connection string

Update your DATABASE_URL in your .env file to include the replica set name:

env
# Before
DATABASE_URL="mongodb://localhost:27017/mydb"

# After
DATABASE_URL="mongodb://localhost:27017/mydb?replicaSet=rs0"

If you're using authentication:

env
DATABASE_URL="mongodb://username:password@localhost:27017/mydb?replicaSet=rs0&authSource=admin"
6Configure MongoDB replica set with Docker

If you're using Docker, create or update your docker-compose.yml:

yaml
version: '3.8'
services:
  mongodb:
    image: mongo:7.0
    container_name: mongodb
    command: ["--replSet", "rs0", "--bind_ip_all"]
    ports:
      - "27017:27017"
    volumes:
      - mongodb_data:/data/db
    healthcheck:
      test: echo "try { rs.status() } catch (err) { rs.initiate({_id:'rs0',members:[{_id:0,host:'localhost:27017'}]}) }" | mongosh --port 27017 --quiet
      interval: 5s
      timeout: 30s
      start_period: 0s
      retries: 30

volumes:
  mongodb_data:

Start the container:

bash
docker-compose up -d

The healthcheck will automatically initialize the replica set.

7Verify the setup works with Prisma

Test your Prisma connection:

bash
npx prisma db push

Or run a simple query in your application:

typescript
import { PrismaClient } from '@prisma/client';

const prisma = new PrismaClient();

async function test() {
  const result = await prisma.user.create({
    data: {
      name: "Test User",
      email: "test@example.com"
    }
  });
  console.log("Success!", result);
}

test();

If the operation completes without the P2031 error, your replica set is configured correctly.

Advanced notes

Production Considerations:

For production deployments, you should use a proper replica set with multiple nodes (typically 3 or more) distributed across different servers or availability zones. This provides:
- High availability through automatic failover
- Data redundancy across multiple servers
- Read scalability through read preference configuration

MongoDB Atlas:

The easiest way to get a production-ready replica set is to use MongoDB Atlas, MongoDB's official cloud database service. Atlas automatically configures replica sets for you and handles all the operational complexity.

Single-Node vs Multi-Node Replica Sets:

While a single-node replica set is sufficient for development and satisfies Prisma's transaction requirements, it doesn't provide the redundancy benefits of a true replica set. In development, this trade-off is acceptable, but production systems should always use multi-node configurations.

Connection String Parameters:

The replicaSet parameter in your connection string must match the replica set name you configured (rs0 in these examples). Other important parameters include:
- retryWrites=true - Automatically retry failed writes (enabled by default)
- w=majority - Write concern for durability guarantees
- readPreference=primary - Ensures reads come from the primary node

Oplog Size:

For development, you can reduce the oplog size to save disk space by starting MongoDB with the --oplogSize flag. The oplog is the capped collection that stores all operations that modify data, used for replication. The default size is 5% of free disk space, but for local development, you can use a smaller value like 50 MB:

bash
mongod --replSet rs0 --oplogSize 50

Frequently asked questions

What does "P2031: Prisma needs to perform transactions, which requires your Mongo" mean?
The P2031 error is a "MongoReplicaSetRequired" error that occurs when Prisma ORM tries to perform operations that require transactions on a MongoDB instance that is not configured as a replica set. MongoDB only allows transactions on replica sets, not on standalone MongoDB instances. Prisma uses transactions internally to support nested writes and avoid partial writes when creating or updating related documents.
How do I fix "P2031: Prisma needs to perform transactions, which requires your Mongo"?
This error occurs when Prisma attempts to use transactions on a standalone MongoDB instance. MongoDB requires replica sets for transaction support, which Prisma uses internally for nested writes and data consistency.
What causes "P2031: Prisma needs to perform transactions, which requires your Mongo"?
MongoDB is running as a standalone instance instead of a replica set MongoDB was installed locally without replica set configuration Docker container running MongoDB without --replSet flag
Is the "P2031: Prisma needs to perform transactions, which requires your Mongo" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading