Error de PostgreSQL: password authentication failed for user

SQLSTATE 28P01 (invalid_password) · Actualizado 9 de julio de 2026

psql: error: connection to server at "localhost" (127.0.0.1), port 5432 failed: FATAL:  password authentication failed for user "app_user"

Llegaste al servidor, pg_hba.conf seleccionó un método de autenticación basado en contraseña para esta conexión, y la comprobación de la contraseña falló. El mensaje del cliente es deliberadamente vago; el log del servidor normalmente dice más.

Qué significa este error

Al cliente solo se le dice "authentication failed" — es intencional, para evitar filtrar información a atacantes. El log del servidor, sin embargo, registra la razón subyacente en el mismo timestamp: que el rol no tenga contraseña asignada, que la contraseña no coincida, o que el formato de la contraseña almacenada no sea utilizable con el método de autenticación que exige pg_hba.conf.

Ese último merece una palabra: las contraseñas se almacenan con hash, usando el algoritmo que tenía password_encryption cuando se estableció la contraseña (scram-sha-256 en las versiones modernas, md5 históricamente). Cambiar password_encryption o el método de pg_hba no convierte las contraseñas ya almacenadas — los desajustes se manifiestan como logins fallidos para contraseñas que son "definitivamente correctas".

Causas comunes

• Contraseña incorrecta o usuario incorrecto — incluyendo "contraseña correcta, entorno incorrecto": credenciales de staging contra producción, o un mapeo de puertos de Docker apuntando a una instancia distinta de la que crees.
• El rol no tiene contraseña establecida (creado con CREATE ROLE y nunca se le dio una). Cualquier contraseña falla; solo el log del servidor dice por qué.
• Desajuste SCRAM/md5: contraseña almacenada como md5 mientras pg_hba requiere scram-sha-256, o una biblioteca de cliente muy antigua que no habla SCRAM.
• Caracteres especiales en un URI de conexión (@, :, /, # en la contraseña) sin percent-encoding, de modo que la contraseña parseada no es la que escribiste.

Cómo diagnosticarlo

• Lee el log del servidor en el timestamp del fallo — casi siempre nombra la causa real.
• Comprueba con qué regla de pg_hba coincide la conexión: SELECT * FROM pg_hba_file_rules; muestra las reglas parseadas en orden (gana la primera coincidencia).
• Prueba con psql directamente, dejando fuera de la ecuación la aplicación, el parseo del URI y el pooler: psql "host=... user=app_user dbname=appdb" y escribe la contraseña interactivamente.

Cómo solucionarlo

• Restablece la contraseña — prefiere el \password de psql sobre una sentencia SQL plana, para que la nueva contraseña no termine en el log del servidor ni en el historial del shell:

  \password app_user

• Alinea el stack en SCRAM: configura password_encryption = 'scram-sha-256', usa scram-sha-256 en pg_hba.conf, y vuelve a establecer todas las contraseñas tras el cambio para que los hashes almacenados coincidan.
• Aplica percent-encoding a las contraseñas en los URI, o pasa la contraseña vía PGPASSWORD/.pgpass/parámetros de conexión en vez del URI.