On this page
Instructs the primary of the replica set to become a secondary. After the primary steps down, eligible secondaries will hold an election for primary.
The method does not immediately step down the primary. If no
electablesecondaries are up to date with the primary, the primary waits up to
secondaryCatchUpPeriodSecs(by default 10 seconds) for a secondary to catch up. Once an electable secondary is available, the method steps down the primary.
Once stepped down, the original primary becomes a secondary and is ineligible from becoming primary again for the remainder of time specified by
For a detailed explanation of the method 's execution, see Behavior.
The method is only valid against the primary and throws an error if run on a non-primary member.
This page documents a
mongoshmethod. This is not the documentation for database commands or language-specific drivers, such as Node.js.
For the database command, see the
For MongoDB API drivers, refer to the language-specific MongoDB driver documentation.
For the legacy
mongoshell documentation, refer to the documentation for the corresponding MongoDB Server release:
rs.stepDown()method has the following parameters:ParameterTypeDescription
The number of seconds to step down the primary, during which time the stepdown member is ineligible for becoming primary. If you specify a non-numeric value, the command uses
The stepdown period starts from the time that the
mongodreceives the command. The stepdown period must be greater than the
Optional. The number of seconds that
mongodwill wait for an electable secondary to catch up to the primary.
secondaryCatchUpPeriodSecsoverrides the default wait time of
rs.stepDown() method attempts to
terminate long running user operations that block the primary
from stepping down, such as an index build, a write operation or a
Availability of Eligible Secondaries
The method then initiates a catchup period where it waits up to
secondaryCatchUpPeriodSeconds, by default 10 seconds, for a
secondary to become up-to-date with the primary. The primary only steps
down if a secondary is up-to-date with the primary during the
catchup period to prevent rollbacks.
If no electable secondary meets this criterion by the end of the waiting period, the primary does not step down and the method errors.
Once the primary steps down successfully, that node cannot become the
primary for the remainder of the
which began when the node received the method.
Starting in MongoDB 4.2,
rs.stepDown() method no
longer closes all client connections.
In MongoDB 4.0 and earlier,
closes all client connections during the step down. Because the
disconnect includes the connection used to run the method,
you cannot retrieve the return status of the method if the
method completes successfully. You can only retrieve the
return status of the method if it errors. When running the
4.0 and earlier method in a script, the script should
account for this behavior.
Writes During Stepdown
All writes to the primary fail during the period starting when the
rs.stepDown() method is received until either a new
primary is elected, or if there are no electable secondaries, the
original primary resumes normal operation.
Writes that were in progress when
rs.stepDown() is run
are killed. In-progress transactions
also fail with
TransientTransactionError and can be
retried as a whole.
The time period where writes fail is at maximum:
secondaryCatchUpPeriodSecs (10s by default) +
electionTimeoutMillis (10s by default).
Changed in version 4.0.2: If the parameter
enableElectionHandoff is true
(default), when a primary steps down from
replSetStepDown command without the
true), the stepped-down primary nominates an eligible secondary
to call an election immediately. Otherwise, secondaries can wait
settings.electionTimeoutMillis before calling an
election. The stepped down primary does not wait for the effects
of the handoff. For more information, see