How to fix Could not start WAL streaming in PostgreSQL

PostgreSQLADVANCEDHIGHUpdated Dec 28, 2025· 167 views

WAL streaming failures in PostgreSQL replication occur when standby servers cannot connect to replication slots or when slots are missing. Common causes include deleted replication slots, case sensitivity issues, or reaching the maximum number of replication slots.

Quick fix

Fixes Could not start WAL streaming

SELECT * FROM pg_replication_slots;
  1. Verify replication slot exists on the primary server
  2. Check replication configuration on the primary server
  3. Recreate the replication slot if it's missing
  4. Verify standby server configuration
postgresql — error
SELECT * FROM pg_replication_slots;
Could not start WAL streaming

What this error means

The "Could not start WAL streaming" error occurs in PostgreSQL streaming replication when a standby server attempts to initiate WAL (Write-Ahead Log) streaming from a primary server but encounters a failure. This typically means the standby cannot begin receiving transaction logs needed to stay synchronized with the primary. The error most commonly appears as "FATAL: could not start WAL streaming: ERROR: replication slot does not exist", indicating the replication infrastructure is not properly configured or has been disrupted. Streaming replication is PostgreSQL's mechanism for continuous data synchronization between primary and standby servers, and any interruption in WAL streaming means the standby cannot receive updates and will fall out of sync with the primary.

Typical symptoms

  • Standby server fails to connect and initialize replication
  • PostgreSQL logs show FATAL or ERROR messages mentioning WAL streaming
  • Replication status shows no active connections from standbys
  • Standby remains disconnected and unable to receive WAL data
  • In Patroni or other clustering tools, replica nodes fail to join the cluster

Common causes

  1. Replication slot has been dropped or deleted on the primary server
  2. Replication slot name contains uppercase letters but standby uses lowercase (or vice versa)
  3. max_replication_slots limit has been reached on the primary server
  4. Streaming replication is disabled (wal_level not set to replica or higher)
  5. max_wal_senders is set to 0 or too low on the primary server
  6. Network connectivity issues between primary and standby servers
  7. Incompatible PostgreSQL versions between primary and standby

How to fix "Could not start WAL streaming"

1Verify replication slot exists on the primary server

Connect to the primary PostgreSQL server and check if the replication slot exists:

sql
SELECT * FROM pg_replication_slots;

Look for your replication slot in the output. If it's missing, the slot needs to be recreated. Note the exact slot name (case-sensitive).

2Check replication configuration on the primary server

Verify that streaming replication is enabled on the primary:

sql
SHOW wal_level;
SHOW max_wal_senders;
SHOW max_replication_slots;

Ensure:
- wal_level is set to replica or logical (not minimal)
- max_wal_senders is greater than 0 (at least 2 for one standby plus backups)
- max_replication_slots is at least the number of standby servers you have

If changes are needed, edit postgresql.conf and restart the primary server.

3Recreate the replication slot if it's missing

If the slot does not exist from Step 1, recreate it on the primary server:

sql
-- For physical replication (streaming replication)
SELECT pg_create_physical_replication_slot('your_slot_name');

-- For logical replication (if applicable)
SELECT pg_create_logical_replication_slot('your_slot_name', 'test_decoding');

Replace your_slot_name with your actual slot name. Use the exact same name in the standby's configuration.

4Verify standby server configuration

On the standby server, check the recovery configuration file (recovery.conf in PostgreSQL 11 and earlier, or signal files in PostgreSQL 12+).

For PostgreSQL 12+, ensure these files exist:
- standby.signal (to enable standby mode)
- postgresql.conf with primary_conninfo pointing to the primary

Example primary_conninfo:

bash
primary_conninfo = 'host=192.168.1.100 port=5432 user=replication password=your_password'

Ensure the replication slot name matches exactly (case-sensitive) with what exists on the primary.

5Restart the standby server

After configuration is verified, restart the PostgreSQL standby server:

bash
sudo systemctl restart postgresql
# or
sudo pg_ctl restart -D /path/to/data/directory

Monitor the logs for connection attempts and errors:

bash
tail -f /var/log/postgresql/postgresql.log
6Monitor replication status

Once the standby connects, verify replication is working on the primary:

sql
SELECT usename, application_name, state, sync_state FROM pg_stat_replication;

You should see your standby in the results with a state of streaming. Monitor replication lag:

sql
SELECT slot_name, slot_type, restart_lsn FROM pg_replication_slots;

Advanced notes

For Patroni clusters, ensure all replicas are configured with identical replication slot names and that Patroni's bootstrap configuration creates slots before replicas attempt to connect. If using logical replication instead of physical, the slot must be created with pg_create_logical_replication_slot and the output plugin must exist. In high-availability setups, monitor pg_wal disk usage to prevent the primary from running out of space while waiting for slow replicas. Consider setting wal_keep_size to retain additional WAL segments as a safety buffer. If replication slots accumulate (become inactive), use pg_drop_replication_slot('slot_name') to clean them up, but only after confirming the corresponding standby no longer exists.

Frequently asked questions

What does "Could not start WAL streaming" mean?
The "Could not start WAL streaming" error occurs in PostgreSQL streaming replication when a standby server attempts to initiate WAL (Write-Ahead Log) streaming from a primary server but encounters a failure. This typically means the standby cannot begin receiving transaction logs needed to stay synchronized with the primary. The error most commonly appears as "FATAL: could not start WAL streaming: ERROR: replication slot does not exist", indicating the replication infrastructure is not properly configured or has been disrupted.
How do I fix "Could not start WAL streaming"?
WAL streaming failures in PostgreSQL replication occur when standby servers cannot connect to replication slots or when slots are missing. Common causes include deleted replication slots, case sensitivity issues, or reaching the maximum number of replication slots.
What causes "Could not start WAL streaming"?
Replication slot has been dropped or deleted on the primary server Replication slot name contains uppercase letters but standby uses lowercase (or vice versa) max_replication_slots limit has been reached on the primary server
Is the "Could not start WAL streaming" error serious?
Yes. This is a high-severity error that usually blocks work until it is fixed, but the steps above resolve it.

Official resources & further reading