Solucionar el error de MySQL "Can't connect through socket"

El mensaje aparece siempre en el peor momento: después de un reinicio, después de una actualización o cuando el disco se ha llenado durante la noche. El texto es casi siempre el mismo:

ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)

Dentro hay dos datos que mucha gente pasa por alto: la ruta y el número entre paréntesis. Los dos indican con bastante precisión dónde tienes que buscar. Este artículo repasa las cinco causas realistas (el servicio no se está ejecutando, una ruta de socket equivocada en la configuración, la aplicación espera una ruta distinta de la que usa el servidor, un problema de permisos, el disco lleno), muestra el diagnóstico en el orden que lleva antes al objetivo y explica la diferencia entre localhost y 127.0.0.1, que por sí sola resuelve alrededor de la mitad de los casos.

Leer con atención el mensaje de error

El cliente ha intentado conectarse a través de un socket de dominio Unix, es decir, mediante un archivo del sistema de archivos y no por la red. La ruta entre comillas es la ruta que espera el cliente. El mensaje no dice si el servidor usa esa misma ruta. Y justo ahí está muchas veces el problema.

El número del final es el código de error del sistema operativo:

El texto exacto varía según el cliente y la versión. Todas estas variantes significan lo mismo:

ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/run/mysqld/mysqld.sock' (2)
ERROR 2002 (HY000): Can't connect to local server through socket '/run/mysqld/mysqld.sock' (2)
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/var/lib/mysql/mysql.sock' (2)
ERROR 2002 (HY000): Can't connect to local MySQL server through socket '/tmp/mysql.sock' (2)

Desde PHP, el mismo error se ve así, porque PHP solo deja pasar el errno pelado:

PDOException: SQLSTATE[HY000] [2002] No such file or directory
Warning: mysqli_connect(): (HY000/2002): No such file or directory

Importante para distinguirlo: ERROR 2003 es otra cosa. Ahí aparecen una dirección IP y un puerto en lugar de una ruta, ese es el camino por TCP. Y ERROR 1045 (28000): Access denied for user significa que la conexión llegó a establecerse y solo falló el inicio de sesión. Para eso tenemos un artículo aparte: Solucionar "Access denied for user" en MySQL.

localhost o 127.0.0.1: la diferencia que explica la mitad de los casos

MySQL y MariaDB tratan localhost como un caso especial. Si ahí pone literalmente localhost, la biblioteca cliente ignora por completo el nombre de host y conecta a través del socket Unix. Si pone 127.0.0.1, la conexión va por TCP al puerto 3306. Eso no es un detalle, es el núcleo del problema: una aplicación con localhost en su configuración alcanza el servidor mediante un archivo cuya ruta obtiene de un sitio distinto al del servidor.

Por eso, la prueba más rápida para saber si hay siquiera un servidor en marcha es esta:

mysql --protocol=TCP -h 127.0.0.1 -P 3306 -u root -p

Si aquí aparece una petición de contraseña o un access denied, el servicio está funcionando y tienes un problema puramente de socket. Si aparece ERROR 2003 ... (111), el servicio no está en marcha o no escucha en TCP.

Como solución permanente, eso sí, pasarse a 127.0.0.1 es la segunda opción. El socket es más rápido, evita la pila de red y, en principio, no es accesible desde fuera. Pero sobre todo: en la tabla de usuarios, 'app'@'localhost' no cubre automáticamente también a 'app'@'127.0.0.1'. Quien cambia el host en la aplicación y después recibe un access denied ha dado justo con ese efecto. Y si te pasas a TCP, comprueba que bind-address no haya quedado sin querer en 0.0.0.0 y la base de datos acabe expuesta en internet. Sobre esto tratan Asegurar MariaDB y MySQL y Configurar el firewall UFW.

Diagnóstico en cinco minutos

Paso 1: ¿se está ejecutando siquiera el servicio?

systemctl status mariadb
systemctl status mysql

En Debian y Ubuntu, la unit de MariaDB se llama mariadb.service (con mysql.service como alias) y la de MySQL mysql.service. En AlmaLinux, Rocky Linux y RHEL se llama mariadb.service y mysqld.service respectivamente. Lo interesante es la línea Active:. Si pone active (running), salta directamente al paso 2. Si pone failed (Result: exit-code) o inactive (dead), la causa está esperando en el log de errores.

Paso 2: ¿qué ruta de socket usa realmente el servidor?

Esto se puede leer de los archivos de configuración sin que el servidor esté en marcha. my_print_defaults evalúa la misma cadena de archivos que el propio servidor, incluidos todos los includes. Indica de una vez todos los grupos que puedan entrar en juego, así el comando funciona en cualquier distribución:

my_print_defaults client client-server mysqld mariadbd | grep -i socket

Los cuatro nombres de grupo no son un exceso de celo, sino la respuesta a tres trampas que, por separado, generan cada una una salida vacía. my_print_defaults client no devuelve absolutamente nada en ninguna de las distribuciones comprobadas, porque en 50-client.cnf (o en /etc/my.cnf.d/client.cnf) todas las opciones están comentadas. En Debian y Ubuntu, el socket está en cambio en el grupo [client-server] de /etc/mysql/mariadb.cnf y aparece allí como --socket=/run/mysqld/mysqld.sock. En la familia Red Hat ese grupo no existe, y allí mysqld entrega el valor --socket=/var/lib/mysql/mysql.sock. Y a partir de MariaDB 11.8, es decir, a partir de Debian 13, el grupo del servidor en 50-server.cnf ya no se llama [mysqld], sino [mariadbd]. Quien allí ejecuta solo my_print_defaults mysqld ve una salida vacía y da por hecho, equivocadamente, que su configuración está vacía.

Como alternativa, si el servidor está en marcha y consigues entrar:

mysql -e "SHOW VARIABLES LIKE 'socket'"

Y sin ningún inicio de sesión, preguntando directamente al kernel qué sockets Unix están ocupados:

ss -lx | grep -i mysql

Si la shell responde ss: command not found, simplemente falta el paquete. En Debian y Ubuntu se llama iproute2, y en AlmaLinux, Rocky Linux y Oracle Linux iproute:

apt-get install -y iproute2
dnf install -y iproute

Con eso ya tienes la ruta que el servidor ofrece realmente. Compárala carácter por carácter con la ruta del mensaje de error. /run/mysqld/mysqld.sock y /var/run/mysqld/mysqld.sock son lo mismo en los sistemas modernos, porque /var/run es un enlace simbólico a /run. /var/lib/mysql/mysql.sock y /tmp/mysql.sock no lo son.

Paso 3: ¿existe el archivo y de quién es?

ls -la /run/mysqld/
ls -la /var/lib/mysql/mysql.sock

Lo esperable es un archivo de tipo s (socket), propiedad de mysql:mysql, con permisos srwxrwxrwx. El directorio superior debería ser drwxr-xr-x mysql mysql. Si falta por completo el directorio /run/mysqld, el servidor nunca ha llegado a arrancar con éxito, porque se crea durante el arranque.

Paso 4: leer el log de errores

Aquí las distribuciones se separan con claridad, y aquí está el motivo más frecuente de que las guías de internet no sirvan de nada. En Ubuntu con MySQL, el servidor escribe en /var/log/mysql/error.log. En Debian con MariaDB, log_error viene comentado de fábrica, el directorio /var/log/mysql/ ni siquiera existe allí y todo acaba en el journal. Usa por tanto la línea que corresponda a tu combinación:

Hay una trampa que merece atención especial, porque no produce ningún error: en un sistema Debian con MariaDB, mysql.service es solo un alias de mariadb.service. systemctl resuelve el alias, pero el journal indexa las entradas bajo el nombre real de la unit. Allí, journalctl -u mysql responde con -- No entries -- y código de salida 0, aunque el journal esté lleno. Quien prueba solo ese comando da el log por vacío y sigue buscando en el sitio equivocado. A la inversa ocurre lo mismo: en un sistema Ubuntu con MySQL, journalctl -u mariadb devuelve igualmente -- No entries --. Si no tienes claro de qué unit se trata, consulta las dos a la vez:

journalctl -u 'mysql*' -u 'mariadb*' --no-pager -n 50

Si quieres un log permanente, añade en Debian y Ubuntu un log_error = /var/log/mysql/error.log al grupo del servidor en /etc/mysql/mariadb.conf.d/50-server.cnf, crea el directorio con install -d -o mysql -g mysql /var/log/mysql y reinicia.

Causa 1: el servicio no se está ejecutando (y por qué)

Un systemctl start mariadb es el acto reflejo, pero si el servicio acaba de morir por su cuenta, por lo general vuelve enseguida al mismo error. Antes vale la pena mirar tres patrones concretos en el log.

Disco lleno

InnoDB se niega a arrancar en cuanto no puede escribir los redo logs. Líneas típicas:

[ERROR] InnoDB: Write to file ./ib_logfile0 failed at offset 0, 1048576 bytes should have been written, only 0 were written
[ERROR] InnoDB: Error number 28 means 'No space left on device'
Can't create/write to file (Errcode: 28 "No space left on device")

Comprueba las dos cosas, el espacio libre y los inodos libres:

df -h
df -i

Un contador de inodos agotado con el disco aparentemente libre pasa más a menudo de lo que se cree, casi siempre por millones de archivos pequeños de sesión o de caché. Qué puedes borrar sin riesgo y qué no lo explica Liberar espacio con el disco lleno en Linux. En /var/lib/mysql no borres nada a mano bajo ningún concepto, y menos aún archivos ib_logfile con una recuperación en curso.

El OOM killer llegó antes

Si el servicio desaparece en pleno funcionamiento y sin mensaje de error, muchas veces ha actuado el kernel:

dmesg -T | grep -i -E "oom|killed process"
journalctl -k | grep -i oom

Una línea como Out of memory: Killed process 1234 (mysqld) no deja lugar a dudas. El error de socket es entonces solo el síntoma. Como remedio sirven un innodb_buffer_pool_size más pequeño, menos workers de PHP simultáneos o algo de swap como colchón, mira Configurar swap contra Out-of-Memory.

Archivo de socket huérfano tras una caída

Si ves esto en el log:

[ERROR] Do you already have another mysqld server running on socket: /run/mysqld/mysqld.sock ?
[ERROR] Aborting

entonces hay un archivo de socket suelto sin ningún proceso detrás. Primero asegúrate de que de verdad no hay ningún servidor en marcha, después elimina el archivo:

systemctl stop mariadb
pgrep -a mysqld
rm -f /run/mysqld/mysqld.sock
systemctl start mariadb

Si pgrep sigue mostrando un proceso, no borres el archivo. De lo contrario, todas las aplicaciones en marcha pierden su conexión, y el servidor lo vuelve a crear en el siguiente arranque mientras el proceso antiguo sigue vivo.

Causa 2: el servidor y la aplicación entienden rutas distintas

Este es el caso en el que todo funciona y aun así no va nada: ss -lx muestra /run/mysqld/mysqld.sock, pero la aplicación busca en /tmp/mysql.sock. Los desencadenantes típicos son servidores compilados a mano, el cambio de MySQL a MariaDB, una migración desde un servidor con panel a un sistema pelado o una instalación de PHP desde un repositorio externo con otros valores por defecto.

La vía limpia consiste en igualar la ruta en exactamente tres sitios a la vez. Primero, en el lado del servidor. El archivo se llama distinto en cada combinación: en Debian y Ubuntu con MariaDB, /etc/mysql/mariadb.conf.d/50-server.cnf; en Debian y Ubuntu con MySQL, /etc/mysql/mysql.conf.d/mysqld.cnf; en AlmaLinux, Rocky Linux y Oracle Linux, /etc/my.cnf.d/mariadb-server.cnf o /etc/my.cnf.d/mysql-server.cnf. En la familia Red Hat no existe ningún directorio /etc/mysql/, allí todo pasa por /etc/my.cnf y /etc/my.cnf.d/:

[mysqld]
socket = /run/mysqld/mysqld.sock

Segundo, para las herramientas de línea de comandos, en 50-client.cnf o en un archivo propio:

[client]
socket = /run/mysqld/mysqld.sock

Tercero, para PHP. Las tres entradas del php.ini deben contener la misma ruta, de lo contrario la configuración del servidor no sirve de nada:

mysqli.default_socket = /run/mysqld/mysqld.sock
pdo_mysql.default_socket = /run/mysqld/mysqld.sock
mysql.default_socket = /run/mysqld/mysqld.sock

Qué php.ini se aplica realmente te lo dice php --ini, siempre que esté instalado el paquete php-cli; si no, la shell solo responde php: command not found. Más importante es la limitación que hay detrás: php --ini nombra el archivo de la línea de comandos, y justo ese casi nunca es el culpable en una aplicación web. El que cuenta es el archivo de FPM, normalmente /etc/php/8.3/fpm/php.ini, y lo que llega de verdad allí lo muestra php-fpm8.3 -i | grep -E 'Loaded Configuration|pdo_mysql.default_socket|mysqli.default_socket'. Después del cambio hace falta reiniciar el servicio FPM, no basta con recargar el servidor web. Si tras eso una aplicación PHP sigue sin entregar nada, la siguiente parada suele ser Solucionar el error nginx 502 Bad Gateway.

En aplicaciones que tienen la ruta cableada y que no puedes tocar, un enlace simbólico ayuda como último recurso:

ln -s /run/mysqld/mysqld.sock /tmp/mysql.sock

Eso no sobrevive a ningún reinicio, eso sí, porque en muchos sistemas /tmp se vacía. De forma permanente, esto corresponde a una regla de tmpfiles o, mejor todavía, a la configuración de la aplicación.

Causa 3: permisos y un /run/mysqld que falta

Si recibes (13) Permission denied, el socket existe, pero tu usuario no llega hasta él. El socket en sí suele estar en 0777, así que el acceso falla en el directorio superior:

chown mysql:mysql /run/mysqld
chmod 755 /run/mysqld

El segundo clásico: /run es un tmpfs y, por tanto, queda vacío después de cada reinicio. El subdirectorio /run/mysqld se vuelve a crear en el arranque, ya sea por systemd-tmpfiles o por el script de inicio. Si en una instalación manual nunca se incluyó la regla correspondiente, el servidor arranca exactamente una vez (mientras el directorio estuvo ahí puesto a mano) y nunca más después del siguiente reinicio. Crea entonces /etc/tmpfiles.d/mysql.conf:

d /run/mysqld 0755 mysql mysql -

Aplicarlo sin reiniciar es posible con systemd-tmpfiles --create. Quien mantiene una unit propia puede poner en su lugar RuntimeDirectory=mysqld, mira Crear un servicio systemd.

Causa 4: AppArmor y SELinux

Estos dos generan la variante más desconcertante del error, porque los permisos del sistema de archivos parecen correctos y el servidor informa igualmente:

[ERROR] Can't start server: Bind on unix socket: Permission denied
[ERROR] Do you already have another mysqld server running on port: 3306 ?

En Ubuntu, el paquete de MySQL trae un perfil de AppArmor. Si has puesto la ruta del socket en algún sitio poco habitual, el perfil impide crear el archivo. Los denials no están en el log de MySQL, sino aquí:

dmesg -T | grep -i apparmor
journalctl -k | grep -i denied

El perfil se amplía en /etc/apparmor.d/local/usr.sbin.mysqld, allí se añade una línea del tipo /run/mysqld/mi.sock rw, y después systemctl reload apparmor. En AlmaLinux y Rocky Linux, SELinux es el equivalente: allí compruebas con ausearch -m avc -ts recent y fijas el contexto con semanage fcontext y restorecon. En ambos casos, lo más cómodo es dejar el socket en la ubicación estándar prevista para él.

Diferencias entre distribuciones de un vistazo

La mayoría de las guías afirman que hay una única ruta para todos los sistemas. Eso no es cierto, y justo por eso fracasa copiar soluciones ajenas. A fecha de julio de 2026:

De ahí salen dos puntos importantes. Primero: Debian no ofrece ningún paquete mysql-server, allí MariaDB es lo establecido. Un apt install mysql-server en Debian falla, y las guías de internet que lo dan por hecho no llevan a ninguna parte. Segundo: en la familia Red Hat el socket vive en el directorio de datos, no bajo /run. Quien migra una aplicación de Debian a AlmaLinux y se lleva la ruta consigo reproduce el error de forma fiable.

Un caso especial al margen: en los containers no hay ni systemd ni el /run/mysqld habitual del host. Si la base de datos corre en un container y la aplicación al lado, no hay ningún socket compartido. Ahí no queda más remedio que usar TCP y el nombre del container como host.

Cómo saber que está realmente resuelto

Un systemctl start sin mensaje de error no demuestra nada. Comprueba en este orden:

systemctl is-active mariadb
ss -lx | grep mysql
mysqladmin ping
mysql -e "SELECT VERSION(), @@socket, @@datadir"

La respuesta mysqld is alive de mysqladmin ping es el verdadero sello de calidad, porque llega por el mismo socket que usa tu aplicación. Después viene la contraprueba desde la capa de aplicación, es decir, no como root, sino como el usuario con el que se ejecuta el servidor web:

sudo -u www-data mysql -u tuusuario -p tubasededatos -e "SELECT 1"

Y por último, la prueba de reinicio. Una parte asombrosamente grande de los errores de socket vuelve tras el siguiente reboot, porque la reparación solo tuvo efecto en tiempo de ejecución (directorio creado a mano, enlace simbólico en /tmp, servicio no habilitado). Por eso:

systemctl enable mariadb
systemctl is-enabled mariadb

Si puedes, reinicia el servidor entero una vez y repite los cuatro comandos de comprobación. En un servidor root de KernelHost eso lleva escasamente un minuto y te ahorra repetir el mismo fallo a las tres de la madrugada.

Cuando la reparación sale mal

Tres situaciones en las que la gente se queda atascada con regularidad.

El servidor ya no arranca después de un cambio de configuración. Una errata en el .cnf provoca una interrupción inmediata, muchas veces con unknown variable. La sintaxis se puede comprobar sin arrancar el servicio, aunque el comando para ello depende del servidor:

mysqld --validate-config --user=mysql
mariadbd --help --verbose | head -40

La primera línea vale exclusivamente para MySQL 8. --validate-config es una opción puramente de MySQL y no existe en ninguna versión de MariaDB, comprobado de la 10.5 a la 11.8. MariaDB responde en su lugar con [ERROR] mysqld: unknown option '--validate-config' seguido de [ERROR] Aborting, y en la familia Red Hat ese mensaje ni siquiera sale por el terminal, solo va al log de errores: allí el comando resulta completamente mudo. También el --user=mysql es obligatorio y no un adorno, porque llamado como root MySQL 8 aborta incluso antes con Please consult the Knowledge Base to find out how to run mysqld as root!. Para MariaDB no hay ningún equivalente de --validate-config. Allí, la segunda línea muestra qué opciones conoce el servidor, y my_print_defaults mysqld mariadbd muestra qué lee realmente de tus archivos.

Guarda una copia antes de cada cambio, así la vuelta atrás es un único cp. Fíjate además en qué archivo escribes: en Debian y Ubuntu, los archivos de conf.d se leen por orden alfabético, y una entrada posterior sobrescribe a otra anterior.

Ya no consigues entrar como root. En MariaDB sobre Debian y Ubuntu, para root@localhost viene preconfigurada la autenticación mediante unix_socket. Es decir: sudo mysql funciona sin contraseña, mientras que mysql -u root -p como usuario normal no, y falla con ERROR 1698 (28000): Access denied for user 'root'@'localhost'. Eso no es un problema de socket, sino el comportamiento previsto.

Has borrado el archivo de socket con el servidor en marcha. El proceso sigue funcionando, mantiene el inodo borrado y ya no es accesible por esa ruta. El archivo no se puede volver a crear a mano, un socket solo nace mediante el bind() del proceso. Aquí solo ayuda un reinicio limpio del servicio. Mientras eso siga pendiente, puedes llegar al servidor por TCP con --protocol=TCP, siempre que skip-networking no esté activado. Aprovecha esa ventana para hacer un dump de las bases de datos más importantes antes de reiniciar.

Un último apunte sobre el orden: no cambies nunca varias cosas a la vez. Primero el estado del servicio, después la comparación de rutas, después los permisos. Quien toca en paralelo el my.cnf, el php.ini y los permisos de archivo no sabe luego qué ha servido de algo, y la próxima vez habrá vuelto a empezar de cero. Si estás montando un sistema desde cero y quieres evitar estas trampas desde el principio, te ayuda la checklist para un nuevo servidor root, y para el stack de base de datos completo con interfaz web, el artículo Instalar Apache, PHP, MySQL y phpMyAdmin en Debian.