Resolver o erro do MySQL "Can't connect through socket"

A mensagem aparece sempre no pior momento possível: depois de um reinício, depois de uma atualização ou quando o disco encheu durante a noite. A formulação é quase sempre a mesma:

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

Há ali duas indicações que muita gente ignora: o caminho e o número entre parênteses. Ambos dizem com bastante precisão onde tem de procurar. Este artigo percorre as cinco causas realistas (o serviço não está a correr, caminho do socket errado na configuração, a aplicação espera um caminho diferente daquele que o servidor usa, problema de permissões, disco cheio), mostra o diagnóstico pela ordem que leva mais depressa ao resultado e explica a diferença entre localhost e 127.0.0.1, que só por si resolve cerca de metade dos casos.

Ler a mensagem de erro com atenção

O cliente tentou ligar-se através de um socket de domínio Unix, ou seja, através de um ficheiro no sistema de ficheiros e não pela rede. O caminho entre aspas é o caminho que o cliente espera. Se o servidor usa esse mesmo caminho, a mensagem não diz. É precisamente aí que está muitas vezes o problema.

O número no fim é o código de erro do sistema operativo:

A formulação varia consoante o cliente e a versão. Estas variantes significam todas o mesmo:

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)

A partir do PHP, o mesmo erro tem este aspeto, porque o PHP se limita a passar adiante o errno em bruto:

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

Importante para distinguir: ERROR 2003 é outra coisa. Ali aparece um endereço IP e uma porta em vez de um caminho, ou seja, o caminho por TCP. E ERROR 1045 (28000): Access denied for user significa que a ligação chegou a ser estabelecida e só a autenticação falhou. Para esse caso temos um artigo próprio: Resolver o "Access denied for user" no MySQL.

localhost ou 127.0.0.1: a diferença que explica metade dos casos

O MySQL e o MariaDB tratam localhost como caso especial. Se ali estiver literalmente localhost, a biblioteca cliente ignora por completo o nome de host e liga-se através do socket Unix. Se ali estiver 127.0.0.1, a ligação vai por TCP para a porta 3306. Isto não é um pormenor, é o cerne do problema: uma aplicação com localhost na configuração chega ao servidor através de um ficheiro cujo caminho vai buscar a um sítio diferente daquele de onde o servidor tira o seu.

Por isso, o teste mais rápido para saber se sequer existe um servidor a correr é este:

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

Se aqui surgir um pedido de palavra-passe ou um Access denied, o serviço está a correr e tem um problema puramente de socket. Se surgir ERROR 2003 ... (111), o serviço não está a correr ou não está à escuta em TCP.

Como solução permanente, porém, mudar para 127.0.0.1 é a segunda melhor opção. O socket é mais rápido, contorna o stack de rede e, por princípio, não é acessível a partir do exterior. Mas sobretudo: na tabela de utilizadores, 'app'@'localhost' não vale automaticamente também para 'app'@'127.0.0.1'. Quem muda o host na aplicação e a seguir recebe um Access denied apanhou exatamente este efeito. E, se mudar para TCP, verifique que bind-address não ficou por descuido em 0.0.0.0 e que a base de dados não passou de repente a estar exposta na Internet. A propósito disso, veja Proteger o MariaDB e o MySQL e Configurar a firewall UFW.

Diagnóstico em cinco minutos

Passo 1: o serviço está sequer a correr?

systemctl status mariadb
systemctl status mysql

Em Debian e Ubuntu, a unit chama-se mariadb.service no caso do MariaDB (com mysql.service como alias) e mysql.service no caso do MySQL. Em AlmaLinux, Rocky Linux e RHEL chama-se mariadb.service ou mysqld.service. A linha interessante é Active:. Se ali estiver active (running), salte já para o passo 2. Se ali estiver failed (Result: exit-code) ou inactive (dead), a causa está no log de erros.

Passo 2: que caminho de socket usa o servidor na realidade?

Isso pode ler-se nos ficheiros de configuração sem ter o servidor a correr. O my_print_defaults avalia a mesma cadeia de ficheiros que o próprio servidor, incluindo todos os includes. Indique de uma só vez todos os grupos que possam entrar em conta e o comando funciona em qualquer distribuição:

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

Os quatro nomes de grupo não são zelo a mais, são a resposta a três armadilhas que, isoladamente, produzem cada uma delas uma saída vazia. O my_print_defaults client não devolve absolutamente nada em nenhuma das distribuições testadas, porque em 50-client.cnf ou em /etc/my.cnf.d/client.cnf todas as opções estão comentadas. Em Debian e Ubuntu, o socket está antes no grupo [client-server] de /etc/mysql/mariadb.cnf e aparece ali como --socket=/run/mysqld/mysqld.sock. Na família Red Hat esse grupo não existe e é o mysqld que devolve o valor --socket=/var/lib/mysql/mysql.sock. E, a partir do MariaDB 11.8, ou seja, a partir do Debian 13, o grupo do servidor em 50-server.cnf já não se chama [mysqld], mas sim [mariadbd]. Quem ali invocar apenas my_print_defaults mysqld vê uma saída vazia e julga erradamente que a sua configuração está vazia.

Em alternativa, se o servidor estiver a correr e conseguir entrar:

mysql -e "SHOW VARIABLES LIKE 'socket'"

E, sem qualquer autenticação, é possível perguntar diretamente ao kernel que sockets Unix estão ocupados:

ss -lx | grep -i mysql

Se a shell responder ss: command not found, falta simplesmente o pacote. Em Debian e Ubuntu chama-se iproute2, em AlmaLinux, Rocky Linux e Oracle Linux iproute:

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

Com isso tem o caminho que o servidor disponibiliza de facto. Compare-o carácter a carácter com o caminho da mensagem de erro. Em sistemas modernos, /run/mysqld/mysqld.sock e /var/run/mysqld/mysqld.sock são a mesma coisa, porque /var/run é um symlink para /run. Já /var/lib/mysql/mysql.sock e /tmp/mysql.sock não são.

Passo 3: o ficheiro existe e a quem pertence?

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

O que se espera é um ficheiro do tipo s (socket), com proprietário mysql:mysql e permissões srwxrwxrwx. O diretório acima deve ser drwxr-xr-x mysql mysql. Se o diretório /run/mysqld faltar por completo, o servidor nunca chegou a arrancar com êxito, porque é no arranque que ele é criado.

Passo 4: ler o log de erros

É aqui que as distribuições se separam com clareza e é aqui que está a razão mais frequente para os guias da Internet não ajudarem. Em Ubuntu com MySQL, o servidor escreve para /var/log/mysql/error.log. Em Debian com MariaDB, o log_error vem comentado por predefinição, o diretório /var/log/mysql/ nem sequer existe ali e tudo vai parar ao journal. Escolha portanto a linha que corresponde à sua combinação:

Há uma armadilha que merece atenção especial, porque não produz erro nenhum: num sistema Debian com MariaDB, o mysql.service é apenas um alias de mariadb.service. O systemctl resolve o alias, mas o journal indexa as entradas sob o nome real da unit. Ali, o journalctl -u mysql responde com -- No entries -- e código de saída 0, mesmo com o journal cheio. Quem experimenta só este comando julga que o log está vazio e continua a procurar no sítio errado. O inverso também é verdade: num sistema Ubuntu com MySQL, o journalctl -u mariadb devolve igualmente -- No entries --. Se não tiver a certeza de qual é a unit em causa, consulte as duas de uma só vez:

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

Se quiser um log permanente, defina em Debian e Ubuntu, dentro de /etc/mysql/mariadb.conf.d/50-server.cnf e no grupo do servidor, um log_error = /var/log/mysql/error.log, crie o diretório com install -d -o mysql -g mysql /var/log/mysql e reinicie.

Causa 1: o serviço não está a correr (e porquê)

O reflexo é um systemctl start mariadb, mas se o serviço acabou de morrer sozinho, em regra volta logo a arrancar para o mesmo erro. Antes disso vale a pena procurar no log três padrões concretos.

Disco cheio

O InnoDB recusa arrancar assim que deixa de conseguir escrever redo logs. Linhas 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")

Verifique as duas coisas, o espaço livre e os inodes livres:

df -h
df -i

Um contador de inodes esgotado com o disco aparentemente livre acontece mais vezes do que se pensa, normalmente por causa de milhões de pequenos ficheiros de sessão ou de cache. O que pode apagar sem risco e o que não pode está em Disco cheio no Linux: libertar espaço. Em /var/lib/mysql não apague nada à mão em circunstância alguma, muito menos ficheiros ib_logfile com uma recovery a decorrer.

O OOM-Killer foi mais rápido

Se o serviço desaparece a meio da operação sem qualquer mensagem de erro, muitas vezes foi o kernel que atuou:

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

Uma linha como Out of memory: Killed process 1234 (mysqld) é inequívoca. O erro de socket é então apenas o sintoma. Os remédios são um innodb_buffer_pool_size mais pequeno, menos workers PHP em simultâneo ou algum swap como almofada, ver Configurar swap contra o Out-of-Memory.

Ficheiro de socket órfão depois de uma falha

Se vir no log:

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

Então há um ficheiro de socket abandonado sem qualquer processo associado. Primeiro há que garantir que não existe mesmo nenhum servidor a correr, só depois se remove o ficheiro:

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

Se o pgrep ainda mostrar um processo, não apague o ficheiro. Caso contrário todas as aplicações em execução perdem a sua ligação e o servidor volta a criá-lo no arranque seguinte, enquanto o processo antigo continua vivo.

Causa 2: servidor e aplicação referem-se a caminhos diferentes

Este é o caso em que tudo corre e mesmo assim nada funciona: o ss -lx mostra /run/mysqld/mysqld.sock, mas a aplicação procura em /tmp/mysql.sock. Os desencadeadores típicos são servidores compilados à mão, a mudança de MySQL para MariaDB, uma migração de um servidor com painel de controlo para um sistema limpo ou uma instalação de PHP vinda de um repositório externo com outras predefinições.

A forma limpa de resolver passa por acertar o caminho em exatamente três sítios. Primeiro, do lado do servidor. O ficheiro para isso tem um nome diferente em cada combinação: em Debian e Ubuntu com MariaDB é /etc/mysql/mariadb.conf.d/50-server.cnf, em Debian e Ubuntu com MySQL é /etc/mysql/mysql.conf.d/mysqld.cnf, em AlmaLinux, Rocky Linux e Oracle Linux é /etc/my.cnf.d/mariadb-server.cnf ou /etc/my.cnf.d/mysql-server.cnf. Um diretório /etc/mysql/ não existe de todo na família Red Hat, ali tudo passa por /etc/my.cnf e /etc/my.cnf.d/:

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

Segundo, para as ferramentas de linha de comandos, em 50-client.cnf ou num ficheiro próprio:

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

Terceiro, para o PHP. As três entradas do php.ini têm de conter o mesmo caminho, caso contrário a configuração do servidor não serve de nada:

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

Qual é o php.ini que de facto se aplica, di-lo o php --ini, desde que o pacote php-cli esteja instalado, caso contrário a shell limita-se a responder php: command not found. Mais importante é a limitação que vem a seguir: o php --ini indica o ficheiro da linha de comandos e é justamente esse que, numa aplicação web, quase nunca é o culpado. O que conta é o ficheiro do FPM, normalmente /etc/php/8.3/fpm/php.ini, e o que ali chega na realidade mostra-o o php-fpm8.3 -i | grep -E 'Loaded Configuration|pdo_mysql.default_socket|mysqli.default_socket'. Depois da alteração é preciso reiniciar o serviço FPM, não basta um reload do servidor web. Se, mesmo assim, uma aplicação PHP continuar a não devolver nada, a paragem seguinte é muitas vezes Resolver o nginx 502 Bad Gateway.

Em aplicações que têm o caminho fixo no código e que não pode alterar, um symlink serve como último recurso:

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

Isso, porém, não sobrevive a um reinício, porque em muitos sistemas o /tmp é esvaziado. De forma permanente, isso pertence a uma regra de tmpfiles ou, melhor ainda, à configuração da aplicação.

Causa 3: permissões e um /run/mysqld em falta

Se receber (13) Permission denied, o socket existe, mas o seu utilizador não lhe consegue chegar. O socket em si costuma estar em 0777, por isso o acesso falha no diretório acima:

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

O segundo clássico: o /run é um tmpfs e fica portanto vazio depois de cada reinício. O subdiretório /run/mysqld é criado de novo no arranque, seja pelo systemd-tmpfiles, seja pelo script de arranque. Se a regra correspondente nunca veio incluída numa instalação manual, o servidor arranca exatamente uma vez (enquanto o diretório criado à mão existir) e, depois do reinício seguinte, nunca mais. Nesse caso crie /etc/tmpfiles.d/mysql.conf:

d /run/mysqld 0755 mysql mysql -

Isso pode aplicar-se sem reiniciar, com systemd-tmpfiles --create. Quem mantém uma unit própria pode em vez disso definir RuntimeDirectory=mysqld, ver Criar um serviço systemd.

Causa 4: AppArmor e SELinux

Estes dois produzem a variante mais confusa do erro, porque as permissões no sistema de ficheiros parecem corretas e mesmo assim o servidor comunica:

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

Em Ubuntu, o pacote do MySQL traz consigo um perfil de AppArmor. Se colocou o caminho do socket num sítio pouco habitual, o perfil proíbe a criação do ficheiro. Os denials não ficam no log do MySQL, ficam aqui:

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

O perfil pode ser alargado em /etc/apparmor.d/local/usr.sbin.mysqld, onde se acrescenta uma linha do género /run/mysqld/meu.sock rw,, seguida de systemctl reload apparmor. Em AlmaLinux e Rocky Linux o equivalente é o SELinux, ali verifica com ausearch -m avc -ts recent e define o contexto com semanage fcontext e restorecon. Nos dois casos, o caminho mais cómodo é simplesmente deixar o socket no local predefinido.

Diferenças entre distribuições num relance

A maioria dos guias afirma que existe um único caminho válido para todos os sistemas. Isso não é verdade e é exatamente aí que falha a cópia de soluções alheias. Situação em julho de 2026:

Há dois pontos importantes a retirar daqui. Primeiro: o Debian não fornece nenhum pacote mysql-server, ali a escolha assente é o MariaDB. Um apt install mysql-server em Debian falha, e os guias correspondentes que circulam na Internet não levam a lado nenhum. Segundo: na família Red Hat o socket fica no diretório de dados, não em /run. Quem migra uma aplicação de Debian para AlmaLinux e leva o caminho consigo produz o erro de forma garantida.

Um caso especial à margem: em containers não há systemd nem o habitual /run/mysqld do host. Se a base de dados corre no container e a aplicação corre ao lado, não existe um socket comum. Ali não há alternativa a TCP com o nome do container como host.

Como saber que o problema está mesmo resolvido

Um systemctl start sem mensagem de erro não prova nada. Verifique por esta ordem:

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

A resposta mysqld is alive do mysqladmin ping é o verdadeiro selo de qualidade, porque chega pelo mesmo socket por onde passa também a sua aplicação. A seguir, a contraprova a partir da camada de aplicação, ou seja, não como root, mas como o utilizador com que o servidor web corre:

sudo -u www-data mysql -u seuutilizador -p suabasededados -e "SELECT 1"

E, por fim, o teste de reinício. Uma parte assustadoramente grande dos erros de socket regressa no reboot seguinte, porque a reparação só teve efeito em tempo de execução (diretório criado à mão, symlink em /tmp, serviço não ativado). Por isso:

systemctl enable mariadb
systemctl is-enabled mariadb

Se for possível, reinicie o servidor por completo uma vez e repita os quatro comandos de verificação. Num servidor root da KernelHost isso demora pouco menos de um minuto e poupa-lhe a repetição do erro às três da manhã.

Quando a reparação corre mal

Três situações em que as pessoas ficam presas com regularidade.

O servidor deixa de arrancar depois de uma alteração à configuração. Um erro de escrita no .cnf leva a uma interrupção imediata, muitas vezes com unknown variable. A sintaxe pode verificar-se sem arrancar o serviço, mas o comando para isso depende do servidor:

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

A primeira linha aplica-se exclusivamente ao MySQL 8. O --validate-config é uma opção puramente do MySQL e não existe em nenhuma versão do MariaDB, verificado da 10.5 à 11.8. Em vez disso, o MariaDB responde com [ERROR] mysqld: unknown option '--validate-config' seguido de [ERROR] Aborting, e na família Red Hat essa mensagem nem sequer aparece no terminal, apenas no log de erros: ali o comando parece completamente mudo. Também o --user=mysql é obrigatório e não um acessório, porque, invocado como root, o MySQL 8 aborta ainda antes disso com Please consult the Knowledge Base to find out how to run mysqld as root!. Para o MariaDB não existe equivalente ao --validate-config. Ali a segunda linha mostra que opções o servidor sequer conhece, e o my_print_defaults mysqld mariadbd mostra o que ele lê na realidade dos seus ficheiros.

Guarde uma cópia antes de cada alteração, assim o caminho de volta é um único cp. Preste também atenção ao ficheiro em que está a escrever: em Debian e Ubuntu, os ficheiros em conf.d são lidos por ordem alfabética e uma entrada posterior sobrepõe-se a uma anterior.

Já não consegue entrar como root. No MariaDB em Debian e Ubuntu, a autenticação através de unix_socket vem predefinida para root@localhost. Isso quer dizer: o sudo mysql funciona sem palavra-passe, ao passo que o mysql -u root -p como utilizador normal não funciona, e falha com ERROR 1698 (28000): Access denied for user 'root'@'localhost'. Isto não é um problema de socket, é comportamento intencional.

Apagou o ficheiro de socket com o servidor a correr. O processo continua a correr, mantém o inode apagado e deixa de estar acessível por esse caminho. O ficheiro não se pode recriar à mão, um socket só nasce do bind() do processo. Aqui só ajuda um reinício limpo do serviço. Enquanto esse reinício não acontece, chega ao servidor por TCP com --protocol=TCP, desde que skip-networking não esteja definido. Aproveite essa janela de tempo para um dump das bases de dados mais importantes, antes de reiniciar.

Uma última nota sobre a ordem dos passos: nunca altere várias coisas ao mesmo tempo. Primeiro o estado do serviço, depois a comparação dos caminhos, depois as permissões. Quem mexe em paralelo no my.cnf, no php.ini e nas permissões dos ficheiros fica sem saber, no fim, o que é que ajudou, e da próxima vez volta ao ponto de partida. Se está a instalar um sistema de raiz e quer evitar estas armadilhas desde o início, ajuda a Checklist para um novo servidor root, e para o stack de base de dados completo com interface web o artigo Instalar Apache, PHP, MySQL e phpMyAdmin em Debian.