p4 failover

Fail over to a standby server.

Syntax conventions

p4 failover [-y] [ -m | [-i] -s serverID ] [-w waitForQuiesce][-v verificationTime][failoverMessage]


Allows the administrator of a standby server to initiate the process of failing over from the current master server to that standby server. In this context, the master server is the server from which the standby server makes its journalcopy (see p4 journalcopy). The "master" server can also be an edge server. The "standby" server can be either a "standby" or "forwarding-standby" server.

Failing over to a "mandatory" (see p4 server Options:) standby when the master server is not part of the failover process ensures that none of the downstream replicas will be ahead of the new master server.

  • For the local High Availability standby server, we recommend mandatory, but only after journalcopying is complete.
  • For the remote Disaster Recovery standby server, we recommend nomandatory

For details, see the Failover topic in the Backup and recovery chapter of Helix Core Server Administrator Guide.

2020.2 and later

Prior to 2020.2

Failover from a mandatory standby server when the master is not participating includes checking the ReplicatingFrom field of the standby server spec for the master's serverID when -s is not specified on the command line.

Failover from a mandatory standby server when the master is not participating used to require specifying -s <serverID>.

Part of the failover process involves stopping the journalcopy and pull threads. If the failover process fails, any pull -L, pull -u, or journalcopy threads that were configured using startup.N configurables will automatically be restarted.

If the failover process fails, the journalcopy and pull threads needed to be restarted manually.



Perform the failover operation. Without this option, p4 failover merely reports what it would do.


Carefully consider the report of what failover would do BEFORE you include the -y option and launch the operation. During the failover process, end-user clients cannot issue commands against the server.

-v Specifies the verificationTime as a number of seconds prior to the launch of the failover command. The default value of 300 seconds means that any file content that was updated from 1 - 300 seconds prior to launch of failover will be verified. This is to ensure that this file content will be correct when the failover process completes on the new master server. The failover command proceeds as soon as it has determined that the new master server has received correct file content. The legal range is between 0 (no verification) and 43200 seconds (12 hours).


The waiting period in seconds for commands in the master server to complete. At the end of this quiesceWait period, all user commands, regardless of their activity, will be stalled.

If -w is not specified, the default quiesceWait value is 60

You can set the waiting period to any integer value between 0 (immediate) and 3600 seconds (1 hour).

To cancel the failover during the quiesceWait period, press Ctrl-C


Ignore the original master server, even if it is accessible.

This option and the -m option are mutually exclusive.

Using the -i flag when the master server is accessible can result in an undesirable "split-brain" scenario in which two master servers process divergent datasets.


The master server is required to participate in failover, which excludes the -i option. If the master server cannot be accessed by the standby server, the failover will not occur.


If the existing master server participates in failover, the new master automatically gets the serverID of the old master and this option is not required.


Prior to 2020.2, if the standby server could not access the master server, this option was necessary to specify the serverID of the master server.

For 2020.2 and later, if the standby server cannot access the master server, there is automatic checking the ReplicatingFrom field of the standby server spec for the master's serverID when -s is not specified on the command line.


If the master server participates in the failover operation, failoverMessage is the text to display to end-users during the failover operation when end-users attempt to start new commands on the master server. The default message is:

Server currently in failover mode, try again after failover has completed

The failoverMessage must be the final argument specified in the p4 failover command. For example,

p4 failover -w 90 -v 500 -y The Perforce server is undergoing scheduled maintenance

and quotation marks are not required.


See Global options

Usage Notes

Can File Arguments Use Revision Specifier? Can File Arguments Use Revision Range? Minimal Access Level Required




Related commands

To copy journal data from a master server to the local file system of a standby replica

p4 journalcopy

To copy the file content of the files that have been added or updated (according to the replicated journal data)

p4 pull -u

To retrieve the journal records from the journalcopy files created by the p4 journalcopy, and to apply these to the standby’s database

p4 pull -L

To reestablish the relationship between the commit server and the standby server to what it was prior to failover p4 failback