Why is it dangerous to perform asynchronous non-database tasks (like sending an email or calling an API) inside a session.withTransaction() block?

Question

Accepted Answer

Mixing asynchronous non-database tasks (like sending emails, calling external APIs, or writing to files) inside a MongoDB transaction block is a fundamental anti-pattern that can lead to serious data inconsistencies and duplicate side effects . Transactions are designed to manage database state, and the `withTransaction` method automatically retries the entire operation on transient errors (like WriteConflict). If your external API call is inside that retried block, you risk sending the same email multiple times or performing the same external action repeatedly without any rollback mechanism . The `session.withTransaction()` method in the MongoDB Node.js driver automatically retries the transaction if it encounters a `TransientTransactionError` (like WriteConflict). This is excellent for database consistency but catastrophic for external systems. Consider this problematic code: await session.withTransaction(async () => {
  await accounts.updateOne(
    { _id: fromAccount },
    { $inc: { balance: -amount } }
  );
  
  await accounts.updateOne(
    { _id: toAccount },
    { $inc: { balance: amount } }
  );
  
  // ❌ DANGEROUS - This could run multiple times!
  await emailService.sendNotification({
    to: 'user@example.com',
    subject: 'Transfer complete',
    body: `You sent ${amount}`
  });
});

// If a WriteConflict occurs and the transaction retries,
// the user receives duplicate emails.
// If the email service is down, the transaction fails and funds aren't moved,
// but the email might have been sent before the failure. The industry-standard solution is to separate database operations from external side effects using the **Transactional Outbox pattern** . You perform all database changes within the transaction, including writing to an 'outbox' collection that records the emails to send or events to publish. Only after the transaction successfully commits do you read from the outbox and send the external notifications. await session.withTransaction(async () => {
  // 1. Database operations only
  await accounts.updateOne(
    { _id: fromAccount },
    { $inc: { balance: -amount } },
    { session }
  );
  
  await accounts.updateOne(
    { _id: toAccount },
    { $inc: { balance: amount } },
    { session }
  );
  
  // 2. Write the external action to an outbox (still inside transaction)
  await outbox.insertOne({
    type: 'email',
    payload: {
      to: 'user@example.com',
      subject: 'Transfer complete',
      body: `You sent ${amount}`
    },
    processed: false,
    createdAt: new Date()
  }, { session });
});

// AFTER the transaction commits successfully:
// Process outbox entries in a background job
const pendingEmails = await outbox.find({ processed: false }).toArray();
for (const email of pendingEmails) {
  try {
    await emailService.sendNotification(email.payload);
    await outbox.updateOne(
      { _id: email._id },
      { $set: { processed: true } }
    );
  } catch (error) {
    // Log error and retry later
    console.error('Failed to send email, will retry:', error);
  }
}

// This ensures at-least-once delivery without risking
// duplicate side effects from transaction retries. Transactions should contain only database operations—no external API calls, file I/O, or other non-transactional side effects . Use the Transactional Outbox pattern to reliably publish events after commit . Implement idempotency keys in external APIs to safely handle retries if you must call them at all . If you absolutely must call an external API after a transaction, do it **after** the transaction commits successfully, never inside the retryable block . Remember that `withTransaction` can retry the callback multiple times—your code must be idempotent if it performs any non-database operations .

Why is it dangerous to perform asynchronous non-database tasks (like sending an email or calling an API) inside a session.withTransaction() block?

Performing asynchronous non-database tasks inside a transaction block is dangerous because transaction retries can cause duplicate executions, and transaction failures can lead to inconsistent state where external side effects have already occurred.

Why is it dangerous to perform asynchronous non-database tasks (like sending an email or calling an API) inside a session.withTransaction() block?

Performing asynchronous non-database tasks inside a transaction block is dangerous because transaction retries can cause duplicate executions, and transaction failures can lead to inconsistent state where external side effects have already occurred.

Scenario Questions

Follow-up Questions