Risolvere l'errore MySQL "Can't connect through socket"

Il messaggio arriva sempre nel momento peggiore: dopo un riavvio, dopo un aggiornamento oppure quando di notte il disco si è riempito. Il testo è quasi sempre lo stesso:

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

Dentro ci sono due informazioni che in molti saltano: il percorso e il numero tra parentesi. Entrambi dicono con buona precisione dove devi cercare. Questo articolo passa in rassegna le cinque cause realistiche (servizio non in esecuzione, percorso del socket sbagliato nella configurazione, applicazione che si aspetta un percorso diverso da quello usato dal server, problema di permessi, disco pieno), mostra la diagnosi nell'ordine che porta al risultato più in fretta e spiega la differenza tra localhost e 127.0.0.1, che da sola risolve circa la metà dei casi.

Leggere il messaggio di errore parola per parola

Il client ha provato a collegarsi tramite un socket di dominio Unix, quindi tramite un file nel filesystem e non tramite la rete. Il percorso tra apici è quello che si aspetta il client. Se poi il server usi davvero lo stesso percorso, il messaggio non lo dice. Ed è proprio lì che spesso si nasconde il problema.

Il numero alla fine è il codice di errore del sistema operativo:

A seconda del client e della versione il testo cambia un po'. Queste varianti significano tutte la stessa cosa:

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)

Da PHP lo stesso errore si presenta così, perché PHP si limita a inoltrare l'errno nudo e crudo:

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

Importante per distinguere i casi: ERROR 2003 è un'altra cosa. Lì compaiono un indirizzo IP e una porta al posto di un percorso, ed è la via TCP. E ERROR 1045 (28000): Access denied for user significa che la connessione c'era e che a fallire è stata solo l'autenticazione. A quel caso abbiamo dedicato un articolo a parte: risolvere l'errore MySQL "Access denied for user".

localhost o 127.0.0.1: la differenza che spiega metà dei casi

MySQL e MariaDB trattano localhost come un caso speciale. Se lì c'è scritto letteralmente localhost, la libreria client ignora completamente il nome host e si collega tramite il socket Unix. Se invece c'è 127.0.0.1, la connessione passa da TCP sulla porta 3306. Non è un dettaglio, è il cuore del problema: un'applicazione che ha localhost nella configurazione raggiunge il server attraverso un file, e il percorso di quel file lo ricava da tutt'altra parte rispetto al server.

Il test più rapido per capire se un server sia davvero in esecuzione è quindi questo:

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

Se a questo punto ti viene chiesta la password oppure ricevi un Access denied, allora il servizio gira e il tuo è un puro problema di socket. Se invece arriva ERROR 2003 ... (111), il servizio non è in esecuzione oppure non è in ascolto su TCP.

Come soluzione definitiva, però, passare a 127.0.0.1 resta la seconda scelta. Il socket è più veloce, evita lo stack di rete e dall'esterno non è raggiungibile per principio. Soprattutto: nella tabella degli utenti 'app'@'localhost' non vale automaticamente anche per 'app'@'127.0.0.1'. Chi cambia l'host nell'applicazione e subito dopo si prende un Access denied ha incontrato esattamente questo effetto. E se passi a TCP, verifica che bind-address non finisca per sbaglio su 0.0.0.0, con il database improvvisamente esposto su internet. In tema ci sono mettere in sicurezza MariaDB e MySQL e configurare il firewall UFW.

Diagnosi in cinque minuti

Passo 1: il servizio è davvero in esecuzione?

systemctl status mariadb
systemctl status mysql

Su Debian e Ubuntu con MariaDB la unit si chiama mariadb.service (con mysql.service come alias), con MySQL mysql.service. Su AlmaLinux, Rocky Linux e RHEL si chiama mariadb.service ovvero mysqld.service. La riga interessante è Active:. Se lì trovi active (running), salta direttamente al passo 2. Se trovi failed (Result: exit-code) oppure inactive (dead), la causa va cercata nel log degli errori.

Passo 2: quale percorso del socket usa davvero il server?

Lo si ricava dai file di configurazione anche senza un server in esecuzione. my_print_defaults valuta la stessa catena di file che valuta il server stesso, inclusi tutti gli include. Indica tutti i gruppi possibili in una volta sola: così il comando funziona su qualsiasi distribuzione:

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

I quattro nomi di gruppo non sono eccesso di zelo, ma la risposta a tre trappole che, prese singolarmente, producono ciascuna un output vuoto. my_print_defaults client non restituisce assolutamente nulla su nessuna delle distribuzioni verificate, perché in 50-client.cnf ovvero in /etc/my.cnf.d/client.cnf tutte le opzioni sono commentate. Su Debian e Ubuntu il socket sta invece nel gruppo [client-server] di /etc/mysql/mariadb.cnf e lì compare come --socket=/run/mysqld/mysqld.sock. Sulla famiglia Red Hat questo gruppo non esiste, e a fornire il valore --socket=/var/lib/mysql/mysql.sock è mysqld. Infine, a partire da MariaDB 11.8, quindi da Debian 13, il gruppo del server in 50-server.cnf non si chiama più [mysqld] ma [mariadbd]. Chi lì invoca solo my_print_defaults mysqld vede un output vuoto e crede erroneamente che la propria configurazione sia vuota.

In alternativa, se il server è in esecuzione e riesci a entrarci:

mysql -e "SHOW VARIABLES LIKE 'socket'"

E senza alcuna autenticazione, chiedendo direttamente al kernel quali socket Unix risultano occupati:

ss -lx | grep -i mysql

Se la shell risponde ss: command not found, manca semplicemente il pacchetto. Su Debian e Ubuntu si chiama iproute2, su AlmaLinux, Rocky Linux e Oracle Linux iproute:

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

Adesso hai il percorso che il server mette davvero a disposizione. Confrontalo carattere per carattere con quello del messaggio di errore. /run/mysqld/mysqld.sock e /var/run/mysqld/mysqld.sock sui sistemi moderni sono la stessa cosa, perché /var/run è un link simbolico a /run. /var/lib/mysql/mysql.sock e /tmp/mysql.sock non lo sono.

Passo 3: il file esiste, e a chi appartiene?

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

Ti aspetti un file di tipo s (socket), con proprietario mysql:mysql e permessi srwxrwxrwx. La directory che lo contiene dovrebbe essere drwxr-xr-x mysql mysql. Se la directory /run/mysqld manca del tutto, il server non è mai partito con successo, perché viene creata proprio all'avvio.

Passo 4: leggere il log degli errori

Qui le distribuzioni divergono parecchio, ed è qui che si nasconde il motivo più frequente per cui le guide trovate in rete non aiutano. Su Ubuntu con MySQL il server scrive in /var/log/mysql/error.log. Su Debian con MariaDB log_error è commentato per impostazione predefinita, la directory /var/log/mysql/ lì non esiste proprio e tutto finisce nel journal. Prendi quindi la riga che corrisponde alla tua combinazione:

Una trappola merita attenzione particolare, perché non produce alcun errore: su un sistema Debian con MariaDB, mysql.service è soltanto un alias di mariadb.service. systemctl risolve l'alias, ma il journal indicizza le voci sotto il nome reale della unit. Lì journalctl -u mysql risponde con -- No entries -- e codice di uscita 0, anche se il journal è pieno. Chi prova solo questo comando crede che il log sia vuoto e continua a cercare nel posto sbagliato. Vale anche il contrario: su un sistema Ubuntu con MySQL, journalctl -u mariadb risponde a sua volta -- No entries --. Se non sei sicuro di quale unit si tratti, interrogale entrambe in una volta sola:

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

Se vuoi un log permanente, su Debian e Ubuntu imposta in /etc/mysql/mariadb.conf.d/50-server.cnf, nel gruppo del server, un log_error = /var/log/mysql/error.log, crea la directory con install -d -o mysql -g mysql /var/log/mysql e riavvia.

Causa 1: il servizio non è in esecuzione (e il motivo)

Il riflesso è un systemctl start mariadb, ma se il servizio è appena morto da solo, di norma riparte e finisce subito nello stesso errore. Prima conviene dare un'occhiata a tre schemi concreti nel log.

Disco pieno

InnoDB rifiuta di partire non appena non riesce più a scrivere i redo log. Righe tipiche:

[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")

Controlla entrambe le cose, lo spazio libero e gli inode liberi:

df -h
df -i

Un contatore di inode esaurito con un disco apparentemente libero capita più spesso di quanto si creda, di solito per milioni di piccoli file di sessione o di cache. Che cosa puoi cancellare senza rischi e che cosa no lo trovi in disco pieno su Linux, come fare pulizia. In /var/lib/mysql non cancellare assolutamente nulla a mano, in particolare nessun file ib_logfile mentre è in corso un recovery.

L'OOM killer è arrivato prima

Se il servizio sparisce nel bel mezzo del lavoro senza alcun messaggio di errore, spesso ha colpito il kernel:

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

Una riga come Out of memory: Killed process 1234 (mysqld) non lascia dubbi. L'errore del socket è allora solo il sintomo. I rimedi sono una innodb_buffer_pool_size più piccola, meno worker PHP in parallelo oppure un po' di swap come cuscinetto, vedi configurare lo swap contro l'Out of Memory.

File socket orfano dopo un crash

Se nel log vedi:

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

allora c'è in giro un file socket senza alcun processo che gli corrisponda. Prima assicurati che non sia davvero in esecuzione nessun server, poi rimuovi il file:

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

Se pgrep mostra ancora un processo, non cancellare il file. Altrimenti tutte le applicazioni attive perdono la connessione e al riavvio successivo il server lo ricrea, mentre il vecchio processo continua a vivere.

Causa 2: server e applicazione intendono percorsi diversi

È il caso in cui tutto funziona e ciononostante non funziona niente: ss -lx mostra /run/mysqld/mysqld.sock, ma l'applicazione cerca in /tmp/mysql.sock. Gli inneschi tipici sono i server compilati a mano, il passaggio da MySQL a MariaDB, una migrazione da un server con pannello a un sistema nudo oppure un'installazione di PHP da un repository esterno con impostazioni predefinite diverse.

La strada pulita è allineare il percorso in esattamente tre punti. Primo, lato server. Il file cambia nome a seconda della combinazione: su Debian e Ubuntu con MariaDB è /etc/mysql/mariadb.conf.d/50-server.cnf, su Debian e Ubuntu con MySQL /etc/mysql/mysql.conf.d/mysqld.cnf, su AlmaLinux, Rocky Linux e Oracle Linux /etc/my.cnf.d/mariadb-server.cnf ovvero /etc/my.cnf.d/mysql-server.cnf. Sulla famiglia Red Hat una directory /etc/mysql/ non esiste proprio, lì passa tutto da /etc/my.cnf e /etc/my.cnf.d/:

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

Secondo, per gli strumenti da riga di comando, in 50-client.cnf oppure in un file dedicato:

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

Terzo, per PHP. Le tre voci nel php.ini devono contenere lo stesso percorso, altrimenti la configurazione del server non serve a nulla:

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

Quale php.ini valga davvero te lo dice php --ini, sempre che il pacchetto php-cli sia installato, altrimenti la shell risponde solo con php: command not found. Più importante è il limite che c'è dietro: php --ini indica il file della riga di comando, e proprio quello, con un'applicazione web, non è quasi mai il colpevole. A contare è il file di FPM, di solito /etc/php/8.3/fpm/php.ini, e quello che lì arriva davvero lo mostra php-fpm8.3 -i | grep -E 'Loaded Configuration|pdo_mysql.default_socket|mysqli.default_socket'. Dopo la modifica serve un riavvio del servizio FPM, non basta un reload del webserver. Se poi un'applicazione PHP continua a non restituire nulla, la tappa successiva è spesso risolvere l'errore nginx 502 Bad Gateway.

Con le applicazioni che hanno il percorso cablato nel codice e che non puoi toccare, come ultima istanza aiuta un link simbolico:

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

Questo però non sopravvive a un riavvio, perché su molti sistemi /tmp viene svuotato. In modo permanente la cosa va messa in una regola tmpfiles o, meglio ancora, nella configurazione dell'applicazione.

Causa 3: permessi e una /run/mysqld mancante

Se ricevi (13) Permission denied, il socket esiste ma il tuo utente non ci arriva. Il socket in sé di solito è a 0777, quindi l'accesso fallisce sulla directory che lo contiene:

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

Il secondo classico: /run è un tmpfs e quindi dopo ogni riavvio è vuoto. La sottodirectory /run/mysqld viene ricreata all'avvio, o da systemd-tmpfiles o dallo script di avvio. Se con un'installazione manuale la regola relativa non è mai stata fornita, il server parte esattamente una volta (finché la directory c'era perché creata a mano) e dopo il riavvio successivo non parte mai più. In quel caso crea /etc/tmpfiles.d/mysql.conf:

d /run/mysqld 0755 mysql mysql -

Si applica senza riavvio con systemd-tmpfiles --create. Chi gestisce una unit propria può invece impostare RuntimeDirectory=mysqld, vedi creare un servizio systemd.

Causa 4: AppArmor e SELinux

Questi due producono la variante più confusa dell'errore, perché i permessi nel filesystem sembrano corretti e il server segnala comunque:

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

Su Ubuntu il pacchetto MySQL porta con sé un profilo AppArmor. Se hai spostato il percorso del socket in una posizione insolita, il profilo vieta la creazione del file. I denial non finiscono nel log di MySQL, ma qui:

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

Il profilo si estende in /etc/apparmor.d/local/usr.sbin.mysqld, dove va inserita una riga come /run/mysqld/mein.sock rw,, seguita da systemctl reload apparmor. Su AlmaLinux e Rocky Linux la controparte è SELinux: lì controlli con ausearch -m avc -ts recent e imposti il contesto con semanage fcontext e restorecon. In entrambi i casi la strada più comoda è semplicemente lasciare il socket nella posizione standard prevista.

Differenze tra le distribuzioni in breve

La maggior parte delle guide sostiene che esista un unico percorso valido per tutti i sistemi. Non è vero, ed è esattamente qui che fallisce il copia e incolla delle soluzioni altrui. Situazione a luglio 2026:

Da qui si ricavano due punti importanti. Primo: Debian non fornisce alcun pacchetto mysql-server, lì la scelta è MariaDB. Un apt install mysql-server su Debian fallisce, e le guide corrispondenti che si trovano in rete non portano da nessuna parte. Secondo: sulla famiglia Red Hat il socket sta nella directory dei dati, non sotto /run. Chi sposta un'applicazione da Debian ad AlmaLinux portandosi dietro il percorso riproduce l'errore in modo affidabile.

Un caso particolare a margine: nei container non esistono né systemd né la solita /run/mysqld dell'host. Se il database gira nel container e l'applicazione gira accanto, non esiste alcun socket condiviso. Lì non si scappa: servono TCP e il nome del container come host.

Come capire che il problema è davvero risolto

Un systemctl start senza messaggi di errore non è una prova. Controlla in quest'ordine:

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

La risposta mysqld is alive di mysqladmin ping è il vero marchio di garanzia, perché arriva attraverso lo stesso socket che usa anche la tua applicazione. Poi la controprova dal livello applicativo, quindi non come root ma come l'utente con cui gira il webserver:

sudo -u www-data mysql -u tuoutente -p tuodatabase -e "SELECT 1"

E infine il test del riavvio. Una quota spaventosamente alta degli errori di socket ritorna al reboot successivo, perché la riparazione ha agito solo a runtime (directory creata a mano, link simbolico in /tmp, servizio non abilitato). Quindi:

systemctl enable mariadb
systemctl is-enabled mariadb

Se possibile, riavvia una volta il server per intero e ripeti i quattro comandi di verifica. Su un server root KernelHost è questione di un minuto scarso e ti risparmia di rivedere lo stesso errore alle tre di notte.

Quando la riparazione va storta

Tre situazioni in cui ci si blocca regolarmente.

Dopo una modifica alla configurazione il server non parte più affatto. Un errore di battitura nel .cnf porta a un'interruzione immediata, spesso con unknown variable. La sintassi si può verificare senza avviare il servizio, ma il comando dipende dal server:

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

La prima riga vale esclusivamente per MySQL 8. --validate-config è un'opzione solo di MySQL e non esiste in nessuna versione di MariaDB, verificato dalla 10.5 alla 11.8. MariaDB risponde invece con [ERROR] mysqld: unknown option '--validate-config' seguito da [ERROR] Aborting, e sulla famiglia Red Hat questo messaggio non compare nemmeno a terminale, ma solo nel log degli errori: lì il comando resta del tutto muto. Anche --user=mysql è obbligatorio e non un accessorio, perché invocato come root MySQL 8 si ferma già prima con Please consult the Knowledge Base to find out how to run mysqld as root!. Per MariaDB non esiste un equivalente di --validate-config. Lì la seconda riga mostra quali opzioni il server conosca davvero, e my_print_defaults mysqld mariadbd mostra che cosa legge realmente dai tuoi file.

Prima di ogni modifica conserva una copia, così la via del ritorno è un solo cp. Fai inoltre attenzione a quale file stai scrivendo: su Debian e Ubuntu i file in conf.d vengono letti in ordine alfabetico, e una voce successiva sovrascrive una precedente.

Non riesci più a entrare come root. Con MariaDB su Debian e Ubuntu, per root@localhost è preimpostata l'autenticazione tramite unix_socket. Vuol dire che sudo mysql funziona senza password, mentre mysql -u root -p da utente normale no, e precisamente con ERROR 1698 (28000): Access denied for user 'root'@'localhost'. Non è un problema di socket, è un comportamento voluto.

Hai cancellato il file socket mentre il server era in esecuzione. Il processo continua a girare, tiene l'inode cancellato e attraverso quel percorso non è più raggiungibile. Il file non si può ricreare a mano, un socket nasce solo dalla bind() del processo. Qui serve soltanto un riavvio pulito del servizio. Finché quello è ancora da fare, raggiungi il server via TCP con --protocol=TCP, a patto che skip-networking non sia impostato. Sfrutta questa finestra per un dump dei database più importanti, prima di riavviare.

Un'ultima indicazione sull'ordine: non cambiare mai più cose contemporaneamente. Prima lo stato del servizio, poi il confronto dei percorsi, poi i permessi. Chi mette mano in parallelo a my.cnf, php.ini e permessi dei file, alla fine non sa che cosa abbia risolto il problema, e la volta dopo ricomincia da capo. Se stai preparando un sistema da zero e vuoi evitare queste trappole fin dall'inizio, ti aiuta la checklist per un nuovo server root, e per lo stack database completo con interfaccia web l'articolo installare Apache, PHP, MySQL e phpMyAdmin su Debian.