Fundamentos de seguridad
Supabase "max client connections reached", explicado
Supabase "max client connections reached": el pooler no tiene sitio para un cliente más. El puerto de tu cadena de conexión decide el límite.

En resumen
- "max client connections reached" en Supabase viene de Supavisor, el pooler que está entre tu app y su base de datos. Ya tiene tantos clientes como permite: 200 en el plan gratuito en modo transacción, puerto 6543.
- En modo sesión, puerto 5432 en la dirección del pooler, el límite es el tamaño del pool, 15 por defecto, y cada cliente conserva su conexión a la base hasta que se desconecta. Una app serverless con esa cadena se rechaza en su cliente número dieciséis.
- Pasa el código serverless al puerto 6543, crea su cliente de base de datos una sola vez con un pool de 1 y cierra las herramientas que dejaste conectadas. Un pool más grande no sube el límite de clientes y se lleva conexiones que Auth necesita.
Tu app lleva semanas funcionando bien. Luego algo trae gente, un lanzamiento o una publicación que se compartió, y las páginas que leen de tu base de datos empiezan a mostrar un error mientras la página de inicio todavía carga. En los logs de funciones de tu hosting hay una línea:
(EMAXCONN) max client connections reached, limit: 200
O, en una app que se conecta en modo sesión, esta otra:
(EMAXCONNSESSION) max clients reached in session mode - max clients are limited to pool_size: 15
Te lo encuentras en una app con servidor propio: una app de Next.js hecha con
v0, Cursor o Claude Code que lee la base de datos con Prisma o Drizzle, una app
de Replit con un servidor Express, una Edge Function que abre su propia
conexión a Postgres. Una página que solo llama a supabase.from(…) pasa por la
Data API, que tiene sus propias conexiones.
El consejo que encontrarás primero para "max client connections reached" en Supabase, incluido el final del propio artículo de ayuda de Supabase sobre la versión de Postgres de este error, es pasar a un tamaño de cómputo mayor. Para una app con mucho tráfico, a veces es lo correcto. En el plan gratuito la solución puede ser un número de puerto. Antes de pagar nada, mira cuál de los dos mensajes te salió y qué puerto usa tu cadena de conexión. Los dos límites los ponen cosas distintas, y solo uno de ellos sube con el precio.
¿Qué significa "max client connections reached" en Supabase?
Supavisor, el pooler de conexiones que está entre tu app y tu base de datos de Supabase, ya tiene tantos clientes conectados como permite, y rechazó al siguiente.
Un cliente, aquí, es una conexión abierta desde tu código: un cliente de base
de datos en una copia de tu servidor en marcha. El mensaje es del propio
Supavisor, del archivo max_connections_error.ex de su código fuente, y llega a
tu app como un error de Postgres con la gravedad FATAL y el código XX000.
Las bibliotecas muestran ese envoltorio de formas distintas, pero las palabras
son las de arriba.
Imagina tu base de datos como una cocina con una barra y un número fijo de taburetes. Cada taburete es una conexión a Postgres, la base de datos de tu proyecto de Supabase, y una petición de datos necesita un taburete mientras dura su pedido. Supavisor es el anfitrión de la puerta. Decide quién se sienta dónde, y tiene una zona de espera para la gente que ya entró y todavía no está comiendo. El mensaje quiere decir que la lista del anfitrión está llena.
¿Qué límite alcanzaste?
Te lo dicen las palabras del error, y también el puerto al final de tu cadena de conexión.
| Lo que ves | Quién lo envió | Qué cuenta | En el plan gratuito |
|---|---|---|---|
(EMAXCONN) max client connections reached, limit: … | Supavisor en modo transacción, puerto 6543 | clientes conectados al pooler a la vez | 200 |
(EMAXCONNSESSION) max clients reached in session mode … | Supavisor en modo sesión, puerto 5432 en el host del pooler | clientes, con el tope en el tamaño del pool | 15 |
remaining connection slots are reserved for roles with the SUPERUSER attribute | el propio Postgres | conexiones a la base | 60 |
sorry, too many clients already | el propio Postgres | todas las conexiones, las reservadas incluidas | 60 |
Las cifras salen de la tabla de la guía de cómputo de Supabase, para Nano, el
tamaño con el que funciona el plan gratuito. Micro, el tamaño de pago más
pequeño, tiene las tres iguales. Los dos mensajes de Postgres vienen del código
fuente de Postgres y llevan el código 53300; Postgres 15 redacta el primero
como remaining connection slots are reserved for non-replication superuser connections.
En la cocina, las dos últimas filas son los taburetes mismos que se acaban. Las dos primeras son el anfitrión, que no deja pasar a nadie más por la puerta.
Tu cadena de conexión dice por qué puerta entraste. Está en las variables de
entorno de tu servidor, a menudo como DATABASE_URL, y la guía de conexión de
Supabase muestra cada tipo:
…@db.[PROJECT-REF].supabase.co:5432/postgreses una conexión directa, que pasa de largo al anfitrión y va derecho a un taburete.…@aws-[INDEX]-[REGION].pooler.supabase.com:5432/postgreses el pooler en modo sesión.…@aws-[INDEX]-[REGION].pooler.supabase.com:6543/postgreses el pooler en modo transacción.
¿Por qué una app de Supabase se queda sin conexiones?
Porque algo abre conexiones más rápido de lo que las devuelve, y las funciones serverless, según la propia descripción de Supabase, abren muchas conexiones de vida corta.
Una función en Vercel, en Netlify o en las Edge Functions de Supabase se ejecuta en tantas copias como pide el tráfico, y cada copia activa guarda su propio cliente de base de datos. La guía de conexión de Supabase hace la cuenta para Postgres.js, una de las bibliotecas de Postgres más comunes: abre por defecto hasta 10 conexiones por copia, y según la guía unas pocas decenas de instancias bastan para agotar el pool.
El modo sesión se llena primero. El anfitrión te da un taburete y te lo quedas hasta que te vas, comas o no. La FAQ de Supabase sobre Supavisor lo dice sin rodeos: cuando el pooler asigna una conexión directa a un cliente, esta se queda con ese cliente hasta que la suelta por su cuenta. Así que el anfitrión solo puede dejar entrar a tantas personas como taburetes tiene para esa cadena de conexión, y por eso el mensaje del modo sesión nombra el tamaño del pool. El código de Supavisor comprueba justo eso: en modo sesión, un cliente nuevo se rechaza en cuanto los ya conectados alcanzan el tamaño del pool. Quince taburetes, y al cliente número dieciséis se le cierra la puerta por muy tranquilos que estén los quince primeros.
El modo transacción deja entrar a mucha más gente. El anfitrión te sienta para un pedido, una sola transacción, y le da el taburete al siguiente en cuanto termina, así que 200 clientes pueden compartir un puñado de conexiones. Aun así tiene una zona de espera de tamaño fijo, y una oleada de copias de funciones que abren varios clientes cada una la llena.
También ocupan taburetes cosas que están fuera de tu app: una herramienta de base de datos como TablePlus o DBeaver que quedó abierta, una automatización en n8n o Make con un paso de Postgres, tu propio portátil ejecutando la app en desarrollo con la cadena de producción, un trabajo de copia de seguridad. Cada uno es un cliente de la cadena que le diste.
Una consulta lenta conserva su taburete más tiempo. Si tus logs también
muestran canceling statement due to statement timeout, arregla primero esa
consulta, porque cada segundo que corre es un segundo con su taburete ocupado.
Ese error tiene su propia guía.
Mira quién ocupa las conexiones
Pregunta a Postgres y luego al panel. Postgres lista cada conexión que tiene abierta, y el panel de Supabase cuenta los clientes del pooler.
En el SQL Editor, esta consulta cuenta las conexiones por rol, por la app que las abrió y por lo que están haciendo:
select usename, application_name, state, count(*)
from pg_stat_activity
where backend_type = 'client backend'
group by usename, application_name, state
order by count(*) desc;
El rol te dice quién es. La guía de Supabase sobre la gestión de conexiones los enumera:
| Rol | Quién es |
|---|---|
authenticator | la Data API, por la que pasa cada llamada a supabase.from(…) |
supabase_auth_admin | Auth, el servicio que inicia la sesión de tus usuarios |
supabase_storage_admin | Storage |
postgres | el panel y las herramientas externas, Prisma y psql incluidos |
| un rol que creaste | quien sea que recibió de ti la contraseña de ese rol |
Un montón de conexiones postgres en estado idle, con un application_name
que reconoces, es un cliente sentado en un taburete sin nada delante.
idle in transaction es el estado que hay que mirar primero: según la guía,
casi siempre significa que la aplicación olvidó confirmar o deshacer, y la
sesión mantiene sus bloqueos mientras siga abierta.
Para el propio pooler, abre Observability en el panel. El informe
Shared Pooler (Supavisor) Client Connections cuenta sus clientes a lo largo
del tiempo. La guía advierte que estos informes muestran la cifra de su última
actualización, y pg_stat_activity es la vista en directo.
Cómo arreglar "max client connections reached" en Supabase
Pasa el código serverless al modo transacción, dale una conexión a cada una de sus copias y deja el modo sesión para los trabajos que necesitan una sesión entera. Hazlo en ese orden.
1. Usa el Transaction pooler para las funciones serverless. En tu proyecto
de Supabase, pulsa Connect arriba en la página, elige Transaction
pooler y copia la cadena. Termina en :6543/postgres. Ponla en el entorno de
tu servidor en lugar de la anterior, con la contraseña de tu base de datos
donde la cadena dice [YOUR-PASSWORD].
El modo transacción no guarda nada entre transacciones, así que los prepared statements tienen que estar desactivados. La guía de Supabase da el ajuste por biblioteca:
| Biblioteca | Ajuste |
|---|---|
| Postgres.js, Drizzle | prepare: false |
| Prisma | pgbouncer=true en la cadena de conexión |
| asyncpg | statement_cache_size=0 |
2. Crea el cliente una sola vez, con un pool de uno. Un cliente creado dentro del manejador de la petición es una conexión nueva en cada petición. La guía de Supabase dice que lo crees una vez al principio del archivo, fuera de cualquier manejador, y que limites su pool a 1, porque todas las invocaciones en esa instancia activa comparten el cliente:
import postgres from 'postgres'
export const sql = postgres(process.env.DATABASE_URL, {
max: 1,
prepare: false,
ssl: 'require',
})
Para Prisma, el mismo consejo es connection_limit=1 en la cadena de conexión,
según la guía de solución de problemas de Prisma de Supabase. Si hiciste la app
con Cursor, Claude Code o v0, es un cambio corto de describirle: el archivo que
crea el cliente de base de datos, la cadena nueva y estos dos ajustes.
3. Deja el modo sesión para un trabajo largo. Una migración, un pg_dump,
una herramienta que abres a mano: cada uno es una sola sesión que quiere
quedarse con su taburete. La guía de Supabase los manda a una conexión directa,
o al modo sesión en una red sin IPv6, y así es como se conecta
una copia de seguridad que corre en los runners de GitHub.
4. Cierra lo que dejaste abierto. Sal de la herramienta de base de datos, detén las ejecuciones de prueba de la automatización y quita la cadena de producción de tu portátil. Una conexión que no puedes cerrar desde su propio extremo se puede terminar desde el SQL Editor. Esta consulta lista las que mantienen una transacción abierta:
select pid, usename, application_name, query_start, query
from pg_stat_activity
where state = 'idle in transaction';
Luego select pg_terminate_backend(pid);, con el pid de esa lista, termina la
sesión. Postgres deshace lo que su transacción abierta había escrito sin
confirmar, así que lee su columna query antes de terminarla.
5. Después, mira el tamaño de cómputo. Si los clientes son todos tráfico real, comparten las conexiones como deben y aun así pasan de 200, el límite sube con el tamaño: Small permite 400 clientes del pooler y Medium 600, según la tabla de cómputo de Supabase. Su base de conocimiento dice que los límites de clientes del pooler compartido son fijos y solo cambian con un tamaño de cómputo mayor, y su guía de cómputo dice que un cambio suele llevar menos de 2 minutos de inactividad.
¿Debo subir el tamaño del pool?
No para arreglar esto. En modo transacción el tamaño del pool no cambia en nada el límite de clientes, y en los dos modos decide cuántas de las conexiones propias de tu base de datos puede tomar el pooler.
El tamaño del pool es el número de taburetes que el anfitrión puede repartir, y la cocina tiene 60 en el plan gratuito. La FAQ de Supabase lo define como el número máximo de conexiones directas que el pooler puede mantener por cada combinación de usuario, base de datos y modo, así que dos cadenas de conexión con un usuario o un modo distinto tienen cada una un pool de ese tamaño. Las mismas 60 sirven a la Data API, a Auth y a Storage, y Storage se conecta a través de Supavisor con un pool propio. La advertencia de la FAQ: si Supavisor usa la mayoría de las conexiones disponibles, te arriesgas a dejar a otros servidores, como Auth, sin acceso a tu base de datos. Auth es el servicio que inicia la sesión de tus usuarios.
Su regla práctica es mantener el pooler por debajo del 40 % de las conexiones si tu app también usa la Data API, e ir hacia el 80 % solo si no la usa.
En modo sesión, un pool más grande sí deja entrar a más clientes, un taburete
cada uno. Eso traslada la fila de la puerta del anfitrión a la cocina. Cuando
allí se acaban los taburetes, Postgres responde remaining connection slots are reserved… al servicio que pregunte a continuación, y ese puede ser Auth.
La cadena de conexión se salta tus políticas
Una cadena de conexión es una contraseña, y el usuario que lleva suele ser
postgres, que según la propia guía de Row Level Security de Supabase tiene
bypassrls. Cada política que escribiste se salta en cada consulta que envía
esa cadena.
Eso cambia lo que tiene que hacer el código de tu servidor. Una página que lee
con supabase.from(…) y tu clave publishable se filtra fila a fila con tus
políticas. La misma página llevada a una ruta de servidor con Prisma o Drizzle
lee todas las filas de la tabla, y lo único que separa a un usuario de las
filas de otro es el where que añade tu ruta. Si llevas páginas a una ruta de
servidor para esquivar este error, comprueba antes de publicar que cada una
filtra por el usuario que ha iniciado sesión.
La cadena tampoco va nunca en una variable cuyo nombre empiece por VITE_ o
NEXT_PUBLIC_. Esos prefijos meten el valor en el código que descarga cada
visitante, y
lo que hacen esos dos prefijos tiene su
propia publicación. Un navegador no puede abrir una conexión a Postgres, así
que una cadena de conexión en el frontend no hace funcionar nada y entrega la
contraseña de la base de datos a cualquiera que abra tu sitio.
Si alguna de tus tablas responde a una petición sin sesión iniciada, y si una clave secreta que reconoce está en el código que envía tu sitio, son dos de las nueve comprobaciones del escaneo gratuito de Reeve. Lee tu app en vivo como lo hace el navegador de un visitante, tarda unos 20 segundos y no necesita cuenta.
Enterarte cuando vuelva a pasar
Este error vuelve cuando vuelve el tráfico, y la hora de más movimiento rara vez es una hora que pasas leyendo logs de funciones.
Reeve Monitor comprueba tu app en vivo desde fuera:
- si está disponible, cada 60 segundos, y cada 15 mientras está caída
- hasta 10 páginas más, leídas en busca de palabras que tienen que estar y palabras que no, como "Algo salió mal"
- un mensaje por email, Telegram, Slack o webhook, con una captura de pantalla y un log guardados 30 días, para que sepas qué página falló y cuándo
- las nueve comprobaciones de seguridad cada hora
- un informe mensual, en lenguaje claro, de lo que vio
Reeve Care guarda una copia de tu base de datos de Supabase de antes del próximo cambio que le hagas:
- una copia cifrada según una programación, en el almacenamiento propio de Reeve en la UE, fuera de tu cuenta de Supabase
- cada copia verificada antes de contar, contando las filas de cada tabla
- también tus archivos subidos, en cuanto conectes una credencial de Storage
- una restauración en un clic, con una copia de seguridad del estado actual tomada antes
- todo lo que hace Monitor
Qué hacer hoy
Qué hacer
- Lee el error y el puerto:
(EMAXCONN)en6543es el límite de clientes del Transaction pooler, y(EMAXCONNSESSION)en5432en la dirección del pooler es el tamaño del pool. - Cuenta quién ocupa las conexiones con
pg_stat_activity, y cierra las herramientas y las ejecuciones de prueba que dejaste conectadas. - Apunta el código serverless a la cadena del Transaction pooler, desactiva los prepared statements y crea el cliente una sola vez con un pool de 1.
- Deja el tamaño del pool dentro de las pautas del 40 % y el 80 % de Supabase, porque Auth y la Data API tiran de las mismas conexiones.
- Comprueba que cada ruta de servidor que usa la cadena de conexión filtra por el usuario que ha iniciado sesión, ya que ninguna política lo hace para esa cadena.
Empieza por la cadena de conexión del entorno de tu servidor: su puerto te dice qué mitad de esta publicación es la tuya. Si llevas páginas a una ruta de servidor como parte del arreglo, la checklist de seguridad de 10 minutos cubre lo que conviene revisar antes de publicarla.
Preguntas frecuentes
¿Qué significa "max client connections reached" en Supabase?
Supavisor, el pooler entre tu app y tu base de datos de Supabase, ya tiene tantos clientes conectados como permite y rechazó uno más. En modo transacción, puerto 6543, el límite lo pone el tamaño de cómputo: 200 en el plan gratuito. El mensaje llega a tu app como un error FATAL con el código XX000 y el prefijo (EMAXCONN).
¿Por qué me sale "max clients reached in session mode" con solo unos pocos usuarios?
En modo sesión cada cliente conserva su conexión a la base hasta que se desconecta, así que Supavisor solo admite tantos clientes como el tamaño del pool, 15 por defecto. Una función serverless abre un cliente en cada copia de sí misma que está en marcha, y un puñado de copias lo llena. Usa la cadena del Transaction pooler, puerto 6543, para el código serverless.
¿Subir el tamaño del pool arregla "max client connections reached"?
No en modo transacción, donde el límite de clientes viene del tamaño de cómputo. El tamaño del pool es cuántas de las conexiones propias de la base puede abrir el pooler, de las mismas 60 del plan gratuito que usan Auth, Storage y la Data API. Supabase aconseja mantener el pooler por debajo del 40 % de ellas si tu app también usa la Data API.
¿Qué diferencia hay entre el puerto 5432 y el 6543 en Supabase?
En la dirección del pooler, 5432 es el modo sesión, donde un cliente conserva su conexión a la base mientras sigue conectado, y 6543 el modo transacción, donde los clientes se turnan en conexiones compartidas, una transacción cada vez. Supabase recomienda 6543 para funciones serverless y edge, y el modo sesión o una conexión directa para trabajos largos como migraciones y pg_dump.
¿Qué significa "remaining connection slots are reserved" en Supabase?
Al propio Postgres se le han acabado las conexiones normales y guarda las últimas para los superusuarios. Cuenta todas las conexiones: tus conexiones directas, las del pooler y las de la Data API, Auth y Storage. En el plan gratuito el total es 60. Averigua quién las ocupa con pg_stat_activity antes de cambiar ningún ajuste.