writeConcernError

writeConcernError is an error object returned by MongoDB servers when a write operation does not satisfy the write concern requested by the client. A write concern specifies the level of acknowledgement required for write operations, such as ws to ensure data is written to a specified number of replica set members.

When a write fails to meet the requested conditions, the server attaches a writeConcernError field to the response document. This field contains an error code, a descriptive message, and optionally a "details" sub-object that can include information about the individual members that caused the failure, such as missing ACKs or timeouts.

The error is generated by the storage engine or replication layer and is distinct from command errors; it is part of the command result. It can be triggered by scenarios like timeouts, full storage volumes, failing replica set members, or insufficient majority. For single-node deployments, writeConcernError may still occur if using unacknowledged writes (w:0) incorrectly with client-side defaults.

Handling writeConcernError involves examining the code and message to determine the underlying cause. Developers may choose to retry the operation, adjust the write concern, or investigate the replica set status. In application logs, writeConcernError entries help diagnose replication lag and disk space issues.

The writeConcernError object is included in all MongoDB drivers that expose the full server response. It is useful for troubleshooting consistency guarantees, planning high-availability strategies, and ensuring that application data is reliably persisted across replica set members.