After updating PostgreSQL to 18.6, why does a wal2json change consumer fail with 'may not be used as an output plugin', and what fixes it?
answer
- a security fix in a minor
- allow-list of decoding plugins
- pgoutput and test_decoding only
- checked whenever decoding starts
- reload, no restart
basics
~10 sPostgreSQL 18.6 added output_plugin_libraries, an allow-list that defaults to 'pgoutput, test_decoding'. Third-party plugins such as wal2json are refused until an administrator reviews them, adds them to the list and reloads the configuration.
solid answer
~40 sLogical decoding loads an output plugin, a shared library named when the slot is created. Built-in subscriptions use `pgoutput`, and `test_decoding` is the shipped example. Before 18.6 any role with `REPLICATION` could name any loadable library, which was an exploit path (CVE-2026-6471). 18.6, and 17.11 on the 17 line, added `output_plugin_libraries`, default `'pgoutput, test_decoding'`. It is checked every time a decoding session starts, so even an existing wal2json slot fails on the consumer's next connection, with SQLSTATE `42501`. Fix: list the plugins in use with `SELECT DISTINCT plugin FROM pg_replication_slots`, review them, add the trusted ones (`output_plugin_libraries = 'pgoutput, test_decoding, wal2json'`) and reload. The parameter is superuser-settable and needs no restart. Until then the consumer's slot keeps retaining WAL.
code
sql · 8 lines-- which plugins do existing logical slots need?
SELECT DISTINCT plugin
FROM pg_replication_slots
WHERE plugin IS NOT NULL;
-- after reviewing wal2json, trust it and reload (no restart)
ALTER SYSTEM SET output_plugin_libraries = 'pgoutput, test_decoding, wal2json';
SELECT pg_reload_conf();go deeper
Recall that logical decoding needs an output plugin, that pgoutput is the built-in one, and that 18.6 only trusts the plugins on a list.
Explain where the check runs, why existing slots fail too, and how adding a name and reloading fixes it without a restart.
Handle it as an incident: inventory slot plugins, review each library's trust, extend the list, and watch WAL retained by the stalled slot.
Fold minor-release security changes into the update process, with a pre-update check of slot plugins against the allow-list.
## Output plugins in one paragraph **Logical decoding** turns WAL records into a stream of row changes. The format of that stream comes from an **output plugin**, a shared library named when a logical replication slot is created and loaded every time the slot is read. PostgreSQL ships two plugins: **`pgoutput`**, which every `CREATE SUBSCRIPTION` uses and which produces the logical replication protocol, and **`test_decoding`**, a readable example. External consumers often install third-party plugins such as wal2json, which emits JSON, or decoderbufs. ## What changed in 18.6 Until this fix, any role with the `REPLICATION` attribute could name **any** loadable library as an output plugin when creating a slot, which let a replication user load code the administrator never intended to expose (CVE-2026-6471). The 18.6 minor release added a server parameter; the 17 line received the same fix in 17.11, and the older supported branches did too. | Property | Value | |---|---| | Name | `output_plugin_libraries` | | Default | `'pgoutput, test_decoding'` | | Who can change it | superuser (`SUSET`); a configuration reload applies it | | Who is restricted | all users, superusers included, unless a superuser overrides it per connection | | Matching | exact library name, no variation in case or path | ## Why an existing consumer breaks The check is not only at slot creation. PostgreSQL verifies the slot's plugin against the list **whenever a decoding session starts**. So after the minor update: - creating a new wal2json slot fails; - an **existing** wal2json slot also fails as soon as the consumer reconnects, which it does after the restart that the update itself required; - the client receives `ERROR: library "wal2json" may not be used as an output plugin` with SQLSTATE `42501` (`insufficient_privilege`), and a hint to add the library to `output_plugin_libraries` and reload; - the server log's detail line shows the current value of the list. The slot is not invalidated or dropped. It stays where it was and keeps retaining WAL for the consumer that can no longer read it, so a long outage turns into a disk-space problem on the publisher. Retention limits are a slot-management topic. Built-in logical replication is unaffected by the default, because subscriptions use `pgoutput`. ## Where the check applies The allow-list covers every route into logical decoding, not only the replication protocol: - slots created by `CREATE SUBSCRIPTION`, which always name `pgoutput`; - slots created with `pg_create_logical_replication_slot('name', 'plugin')`; - SQL-level reads such as `pg_logical_slot_get_changes()` and `pg_logical_slot_peek_changes()`, which also start a decoding session; - external consumers that connect over the replication protocol and stream from their slot. So a DBA inspecting a slot with `test_decoding` keeps working by default, while any tool built on a third-party plugin needs that plugin on the list. ## Fixing it safely 1. **Inventory** the plugins your slots actually use: `SELECT DISTINCT plugin FROM pg_replication_slots WHERE plugin IS NOT NULL;` Refused requests from plugins with no slot yet show up only in the server log. 2. **Review** each third-party library. Adding a name means every `REPLICATION` user may load it, so it must not hand non-superusers extra privileges. 3. **Add** the trusted ones, keeping the built-ins: `output_plugin_libraries = 'pgoutput, test_decoding, wal2json'` in `postgresql.conf` or through `ALTER SYSTEM`. 4. **Reload** with `pg_reload_conf()` or `pg_ctl reload`; no restart is needed. The consumer's next connection succeeds and it resumes from its slot's position. A superuser can also override the list for a single connection with `options=-coutput_plugin_libraries=...` in the connection string, which is useful for a one-off test but not as a permanent fix. ## Related consequences - **Upgrades:** when moving from 17 or later, `pg_upgrade --check` fails if the new cluster's list does not permit the plugins of the old cluster's logical slots; set it on the new cluster first. - **Hardening:** an empty list refuses every plugin, `pgoutput` included, which disables logical decoding on that server entirely. - **Change management:** this arrived in a minor release, and teams that read only major release notes were the ones surprised. A pre-update check that compares `pg_replication_slots.plugin` against the list prevents it.
- Does the new allow-list affect built-in subscriptions created with CREATE SUBSCRIPTION?Not with the default value, because subscriptions always use `pgoutput`, which is on the list. They break only if someone narrows the list to exclude it. An empty value refuses every plugin and so stops logical replication on that publisher.
- What happens to the consumer's slot while the plugin is refused?Nothing visible: it is neither dropped nor invalidated. Its position does not advance because no one can decode from it, so it keeps holding WAL on the publisher. A long outage can fill the disk, which is why the fix should not wait for the next maintenance window.
- The minor update invalidated or dropped the wal2json slots.
- Only new slots are checked; existing slots keep decoding as before.
- Adding wal2json to shared_preload_libraries makes it allowed again.
- Changing output_plugin_libraries requires a full server restart.
- Superusers are exempt from output_plugin_libraries.
Assumes PostgreSQL 18.6; output_plugin_libraries first appeared in the 18.6 and 17.11 minor releases, so older minors accept any loadable plugin.