wal_receiver_timeout

Definition PG 18 manual

Terminate replication connections that are inactive for longer than this amount of time. This is useful for the receiving standby server to detect a primary node crash or network outage. If this value is specified without units, it is taken as milliseconds. The default value is 60 seconds. A value of zero disables the timeout mechanism. This parameter can only be set in the postgresql.conf file or on the server command line.

How it works

Sets the maximum wait time to receive data from the sending server. A configuration reload applies a new value; existing work already in flight is not retroactively changed.

A standby terminates its receiver after this period without sender data, then reconnects according to recovery behavior. It is failure detection, not an end-to-end failover deadline, and must tolerate expected network pauses.

Monitor and change wal_receiver_timeout together with primary_conninfo, primary_slot_name, restore_command. Validate on the relevant server role and real workload, then use its sighup context to choose session change, reload, or restart; a historical boot default is not the current effective value.

Operational considerations

Changing it on the wrong primary, standby, sender, or subscriber role.

Watching only configured bytes/time instead of actual lag, slot position, and worker state.

Failing over to a node that lacks the old primary's capacity or prerequisites.

Using infinite waits or WAL retention to hide a failed consumer.

Workload guidance

OLAP: Read standbys and logical subscribers often see long queries or large transactions. Put explicit bounds on replay/apply and monitor lag, worker saturation, slot restart_lsn, and conflict cancellations.

OLTP: Size wal_receiver_timeout from topology, failover roles, slot/subscription count, and reconnect headroom. Test worst-case primary latency, standby replay, and disk retention before production.

SMALL: Configure only replication capacity that is actually used. Even a small topology needs bounded timeouts and slot lifecycle; unlimited retention is not reliability.