Fix PostgreSQL: Remaining Connection Slots Are Reserved

The error "remaining connection slots are reserved for non-replication superuser connections" means PostgreSQL is not merely busy; it has reached the regular client connection limit and is keeping a small emergency reserve for privileged maintenance access. New application sessions are rejected so an administrator still has a way to connect and fix the system.

The immediate problem is usually a connection storm, a pool misconfiguration, leaked sessions, or too many app instances opening their own database connections. Raising the limit can help in some cases, but it is not the safest first move. Each PostgreSQL backend consumes memory and scheduler time, so the durable fix is to understand who is holding connections and control concurrency at the application or pooler layer.

What the error actually means

PostgreSQL uses max_connections as the upper bound for concurrent client connections. It also keeps reserved slots controlled by settings such as superuser_reserved_connections and, in newer releases, reserved_connections for roles with the pg_use_reserved_connections privilege. When normal clients consume all non-reserved slots, ordinary application users receive the reserved-slot error while privileged users can still get in.

That reserve is intentional. If every slot were available to the app, the database could lock out the person or automation that needs to cancel idle sessions, inspect pg_stat_activity, or apply a safer configuration. Treat the error as a capacity signal and a protection mechanism, not as a message to remove the reserve.

Immediate recovery steps

Start by connecting through the most privileged path your environment provides. In self-hosted PostgreSQL that may be a superuser account on a trusted network. In managed PostgreSQL it may be a provider console, emergency session, or support workflow. Do not terminate sessions blindly before you know whether they are running important transactions.

Once connected, inspect pg_stat_activity. Look for repeated application_name values, long-lived idle in transaction sessions, and clients that opened many more sessions than expected. If a session is truly idle and safe to remove, pg_terminate_backend can release a slot. If the session is running a migration or payment-related write, cancellation may cause a bigger incident than waiting, so confirm the owner before acting.

If a recent deploy caused the spike, the fastest safe fix is usually to roll back the connection change, reduce the app pool size, or scale down excess workers. For example, ten application containers with a pool size of twenty can attempt two hundred database sessions before background jobs, migrations, and admin tools are counted. A small database that worked fine with two containers can fail immediately after horizontal scaling if the pool limit was copied unchanged.

Fix the pool math, not just the parameter

The durable fix is capacity budgeting. Count every process that can open database sessions: web servers, queue workers, cron jobs, migration runners, analytics jobs, local admin tools, and preview environments. Then decide how many active database sessions each component truly needs. Most web apps need far fewer PostgreSQL sessions than concurrent HTTP requests because database work is only part of the request lifecycle.

PgBouncer helps when the application opens many short-lived sessions or when serverless and autoscaled workloads create bursts. In transaction pooling mode, PgBouncer can reuse a smaller number of PostgreSQL server connections across many client connections, as long as the application avoids session-level features that do not survive transaction boundaries. For apps that depend on session state, prepared statements, temporary tables, or session-level settings, session pooling or careful driver configuration may be safer.

Raising max_connections should be deliberate. PostgreSQL documentation notes that the setting affects the number of concurrent connections and requires enough system resources. More backends can increase memory pressure and make contention worse, especially on small instances. If you need more true concurrent database work, the answer may be a larger plan, query tuning, workload separation, or pooling rather than a higher number alone.

A practical checklist

First, reserve a path for emergency access and leave PostgreSQL's reserved slots intact. Next, set explicit pool limits for each application component instead of relying on driver defaults. Then add timeouts that prevent abandoned work from holding slots forever: statement timeouts for runaway queries, idle-in-transaction timeouts for broken transaction scopes, and app-level request timeouts so callers do not wait indefinitely.

After the incident, record the connection budget in the runbook. Include the database max connection limit, the expected reserve, the number of app replicas, each pool size, and the largest safe deploy scale. If you use ArmorDB, the PgBouncer documentation is the right internal next step because pooling is often the cleanest way to absorb bursty app behavior without letting every client map to a PostgreSQL backend. The limits documentation can help you match the budget to the plan you are running.

Takeaway

The reserved-slot error is PostgreSQL protecting the last maintenance connections while telling you the application has outgrown its current connection behavior. Recover by finding and releasing obviously safe sessions, rolling back bad pool changes, or scaling down runaway workers. Prevent it by budgeting connections, adding PgBouncer where it fits, and treating max_connections as a resource decision rather than an unlimited dial.

Sources and further reading

• PostgreSQL documentation: Connection settings
• PostgreSQL documentation: pg_stat_activity
• PostgreSQL documentation: Terminating backend processes
• PgBouncer documentation: Features and pooling modes
• PgBouncer documentation: Configuration