Atlas error: transaction numbers are only allowed on a replica set member or mongos

TL;DR: You are talking to a single node instead of the replica set, usually because of directConnection. Fix the string, not the transaction code. Check the connection string for directConnection=true. Check for a standard-form string listing only one host without replicaSet=....

The fix

TL;DR: You are talking to a single node instead of the replica set, usually because of directConnection. Fix the string, not the transaction code. Check the connection string for directConnection=true. Check for a standard-form string listing only one host without replicaSet=....

The fix

"Transaction numbers are only allowed on a replica set member or mongos"

This error means the driver connected directly to one mongod and bypassed replica set semantics. Transactions need the replica set (or mongos).

Confirm

1. Check the connection string for directConnection=true. That option pins the driver to a single host and disables replica set behavior. It is the usual culprit.
2. Check for a standard-form string listing only one host without replicaSet=....
3. Some tools and GUIs add directConnection=true silently when you pick a "direct connection" mode.

Fix

Remove directConnection=true and, for standard-form strings, include the full host list plus replicaSet=[name]. The SRV string handles this automatically. Keep retryWrites=true.

Verify

Run a trivial multi-document transaction (insert two docs, commit). Success proves replica set semantics are back.

When to use this

• You are seeing this exact error message; match the block above, not just part of it.
• The failing call matches the scenario in the title: Atlas error.
• You want the fastest verified fix before digging through logs.

When not to use this

• Your error text differs from the block above; close cousins often have different causes.
• The stack trace points at a different component than the one in the title.
• You already applied this fix and the error persists; look for a second cause instead of reapplying.

Compatibility

• Not pinned to a specific version; follows current Atlas behavior.

Transaction prerequisites (replica set or mongos, retryWrites) per https://www.mongodb.com/docs/manual/core/transactions/, verified 2026-09-26.