ERROR: logical decoding requires wal_level >= logical
ID: database/pg-wal-level-insufficient
Version Compatibility
| Version | Status | Introduced | Deprecated | Notes |
|---|---|---|---|---|
| 16 | active | — | — | — |
Root Cause
Logical replication or change data capture (Debezium, pgoutput) requires wal_level = logical, but PostgreSQL is running with wal_level = replica (default) or minimal. This parameter requires a PostgreSQL restart to take effect. It slightly increases WAL volume but is required for logical replication, logical decoding, and CDC tools.
genericWorkarounds
-
95% success Set wal_level = logical and restart PostgreSQL
Run: ALTER SYSTEM SET wal_level = 'logical'; Then restart PostgreSQL: systemctl restart postgresql or pg_ctl restart. Verify: SHOW wal_level; Also set max_replication_slots (default 10) and max_wal_senders (default 10) if not already sufficient. Plan a maintenance window as restart causes brief downtime.
-
92% success For managed databases (RDS, Cloud SQL), enable logical replication through the cloud provider's interface
AWS RDS: Set rds.logical_replication = 1 in the parameter group and reboot. GCP Cloud SQL: Set cloudsql.logical_decoding = on and restart. Azure: Set wal_level = logical in server parameters. Managed databases often have logical replication disabled by default for performance.
Dead Ends
Common approaches that don't work:
-
Attempting to change wal_level with ALTER SYSTEM and then just reloading configuration
95% fail
wal_level is a postmaster-level parameter that requires a full PostgreSQL restart, not just a configuration reload (pg_ctl reload / SELECT pg_reload_conf()). The change is written to postgresql.auto.conf but does not take effect until restart.
-
Using pg_basebackup to set up a standby and enabling logical replication on the standby only
90% fail
Logical replication slots can only be created on the primary. A standby inherits the primary's wal_level but cannot create logical replication slots. The primary must have wal_level = logical.