Naprawa błędu MySQL „Can't connect through socket”

Ten komunikat pojawia się zawsze w najgorszym możliwym momencie: po restarcie, po aktualizacji albo wtedy, gdy w nocy zapełnił się dysk. Treść jest niemal zawsze taka sama:

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

Kryją się w nim dwie informacje, które wiele osób pomija: ścieżka oraz liczba w nawiasie. Obie dość dokładnie wskazują, gdzie musisz szukać. Ten artykuł omawia pięć realnych przyczyn (usługa nie działa, błędna ścieżka socketu w konfiguracji, aplikacja oczekuje innej ścieżki niż ta, której używa serwer, problem z uprawnieniami, zapełniony dysk), pokazuje diagnostykę w kolejności, która najszybciej prowadzi do celu, i wyjaśnia różnicę między localhost a 127.0.0.1, która sama w sobie rozwiązuje mniej więcej połowę wszystkich przypadków.

Dokładnie przeczytaj komunikat błędu

Klient próbował połączyć się przez socket uniksowy, czyli przez plik w systemie plików, a nie przez sieć. Ścieżka w cudzysłowie to ścieżka, której oczekuje klient. Czy serwer używa tej samej ścieżki, komunikat nie mówi. I właśnie tam najczęściej leży problem.

Liczba na końcu to kod błędu systemu operacyjnego:

W zależności od klienta i wersji treść komunikatu się różni. Wszystkie te warianty oznaczają dokładnie to samo:

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)

Z poziomu PHP ten sam błąd wygląda tak, ponieważ PHP przekazuje dalej wyłącznie surowy errno:

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

Ważne rozróżnienie: ERROR 2003 to coś innego. Zamiast ścieżki widać tam adres IP i port, czyli drogę przez TCP. Z kolei ERROR 1045 (28000): Access denied for user oznacza, że połączenie zostało nawiązane i nie powiodło się wyłącznie logowanie. Poświęciliśmy temu osobny wpis: Naprawa błędu MySQL „Access denied for user”.

localhost czy 127.0.0.1: różnica, która wyjaśnia połowę przypadków

MySQL i MariaDB traktują localhost jako przypadek szczególny. Jeśli w konfiguracji stoi dosłownie localhost, biblioteka klienta całkowicie ignoruje nazwę hosta i łączy się przez socket uniksowy. Jeśli stoi tam 127.0.0.1, połączenie idzie przez TCP na port 3306. To nie jest szczegół, tylko sedno problemu: aplikacja z wpisem localhost w konfiguracji sięga do serwera przez plik, którego ścieżkę bierze z zupełnie innego miejsca niż sam serwer.

Najszybszy test, czy serwer w ogóle działa, wygląda więc tak:

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

Jeśli pojawi się pytanie o hasło albo komunikat Access denied, usługa działa i masz czysty problem z socketem. Jeśli zobaczysz ERROR 2003 ... (111), usługa nie działa albo nie nasłuchuje na TCP.

Jako rozwiązanie docelowe przełączenie na 127.0.0.1 jest jednak wyborem drugiej kategorii. Socket jest szybszy, omija stos sieciowy i z zewnątrz zasadniczo pozostaje nieosiągalny. Przede wszystkim jednak wpis 'app'@'localhost' w tabeli użytkowników nie obowiązuje automatycznie także dla 'app'@'127.0.0.1'. Kto zmieni host w aplikacji i zaraz potem dostanie Access denied, trafił dokładnie na ten efekt. A jeśli przechodzisz na TCP, sprawdź, czy bind-address nie stoi przypadkiem na 0.0.0.0 i baza nie wisi nagle w internecie. Pasują do tego Zabezpieczanie MariaDB i MySQL oraz Konfiguracja firewalla UFW.

Diagnostyka w pięć minut

Krok 1: czy usługa w ogóle działa?

systemctl status mariadb
systemctl status mysql

W Debianie i Ubuntu unit MariaDB nazywa się mariadb.service (z mysql.service jako aliasem), a przy MySQL jest to mysql.service. W AlmaLinux, Rocky Linux i RHEL nazywa się odpowiednio mariadb.service względnie mysqld.service. Interesuje cię wiersz Active:. Jeśli stoi tam active (running), przeskocz od razu do kroku 2. Jeśli widnieje failed (Result: exit-code) albo inactive (dead), przyczynę znajdziesz w logu błędów.

Krok 2: jakiej ścieżki socketu serwer naprawdę używa?

Da się to odczytać z plików konfiguracyjnych nawet wtedy, gdy serwer nie działa. my_print_defaults przetwarza dokładnie ten sam łańcuch plików co sam serwer, łącznie ze wszystkimi dołączanymi plikami. Podaj od razu wszystkie wchodzące w grę grupy, a polecenie zadziała na każdej dystrybucji:

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

Cztery nazwy grup to nie nadgorliwość, tylko odpowiedź na trzy pułapki, z których każda z osobna daje pustą odpowiedź. my_print_defaults client nie zwraca niczego na żadnej ze sprawdzonych dystrybucji, ponieważ w 50-client.cnf względnie /etc/my.cnf.d/client.cnf wszystkie opcje są zakomentowane. W Debianie i Ubuntu socket stoi zamiast tego w grupie [client-server] pliku /etc/mysql/mariadb.cnf i pojawia się tam jako --socket=/run/mysqld/mysqld.sock. W rodzinie Red Hat ta grupa w ogóle nie istnieje, tam wartość --socket=/var/lib/mysql/mysql.sock zwraca grupa mysqld. A od MariaDB 11.8, czyli od Debiana 13, grupa serwerowa w 50-server.cnf nazywa się już nie [mysqld], lecz [mariadbd]. Kto wywoła tam samo my_print_defaults mysqld, zobaczy pustą odpowiedź i błędnie uzna swoją konfigurację za pustą.

Alternatywnie, jeśli serwer działa i możesz się do niego dostać:

mysql -e "SHOW VARIABLES LIKE 'socket'"

A zupełnie bez logowania, pytając bezpośrednio jądro, które sockety uniksowe są zajęte:

ss -lx | grep -i mysql

Jeśli shell odpowie ss: command not found, po prostu brakuje pakietu. W Debianie i Ubuntu nazywa się on iproute2, a w AlmaLinux, Rocky Linux i Oracle Linux iproute:

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

W ten sposób masz ścieżkę, którą serwer rzeczywiście udostępnia. Porównaj ją znak po znaku ze ścieżką z komunikatu błędu. /run/mysqld/mysqld.sock i /var/run/mysqld/mysqld.sock to na nowoczesnych systemach to samo, bo /var/run jest dowiązaniem symbolicznym do /run. /var/lib/mysql/mysql.sock i /tmp/mysql.sock już nie.

Krok 3: czy plik istnieje i do kogo należy?

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

Spodziewasz się pliku typu s (socket), właściciel mysql:mysql, uprawnienia srwxrwxrwx. Katalog nadrzędny powinien mieć drwxr-xr-x mysql mysql. Jeśli katalogu /run/mysqld w ogóle brakuje, serwer nigdy nie wystartował poprawnie, bo katalog powstaje właśnie przy starcie.

Krok 4: przeczytaj log błędów

Tutaj dystrybucje wyraźnie się rozchodzą i tutaj kryje się najczęstszy powód, dla którego poradniki z sieci nie pomagają. W Ubuntu z MySQL serwer pisze do /var/log/mysql/error.log. W Debianie z MariaDB log_error jest domyślnie zakomentowany, katalog /var/log/mysql/ w ogóle tam nie istnieje, a wszystko trafia do journala. Weź więc ten wiersz, który pasuje do twojej kombinacji:

Jedna pułapka zasługuje przy tym na szczególną uwagę, bo nie generuje żadnego błędu: w systemie Debian z MariaDB mysql.service jest wyłącznie aliasem na mariadb.service. systemctl rozwiązuje ten alias, ale journal indeksuje wpisy pod prawdziwą nazwą unitu. journalctl -u mysql odpowiada tam -- No entries -- z kodem wyjścia 0, mimo że journal jest pełen. Kto spróbuje tylko tego polecenia, uzna log za pusty i będzie szukał dalej w złym miejscu. Odwrotnie działa to tak samo: w systemie Ubuntu z MySQL journalctl -u mariadb również zwróci -- No entries --. Jeśli nie masz pewności, o który unit chodzi, odpytaj oba naraz:

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

Jeśli chcesz mieć trwały log, wpisz w Debianie i Ubuntu w pliku /etc/mysql/mariadb.conf.d/50-server.cnf w grupie serwerowej log_error = /var/log/mysql/error.log, załóż katalog poleceniem install -d -o mysql -g mysql /var/log/mysql i uruchom usługę ponownie.

Przyczyna 1: usługa nie działa (i dlaczego)

Odruchem jest systemctl start mariadb, ale jeśli usługa właśnie sama padła, z reguły wystartuje prosto w ten sam błąd. Wcześniej warto rzucić okiem na trzy konkretne wzorce w logu.

Zapełniony dysk

InnoDB odmawia startu, gdy tylko nie może zapisać redo logów. Typowe wiersze:

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

Sprawdź obie rzeczy: wolne miejsce i wolne inody:

df -h
df -i

Wyczerpane inody przy pozornie wolnym dysku zdarzają się częściej, niż się wydaje, zwykle przez miliony drobnych plików sesji albo cache. Co możesz bezpiecznie skasować, a czego nie, opisuje wpis Zapełniony dysk w Linuksie: jak posprzątać. W katalogu /var/lib/mysql nie kasuj ręcznie absolutnie niczego, a zwłaszcza plików ib_logfile w trakcie trwającego recovery.

OOM killer był szybszy

Jeśli usługa znika w trakcie pracy bez żadnego komunikatu błędu, często uderzyło jądro:

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

Wiersz w rodzaju Out of memory: Killed process 1234 (mysqld) nie pozostawia wątpliwości. Błąd socketu jest wtedy tylko objawem. Środkiem zaradczym są mniejsza wartość innodb_buffer_pool_size, mniej równoległych workerów PHP albo trochę swapu jako bufor, zobacz Konfiguracja swapu przeciw Out-of-Memory.

Osierocony plik socketu po awarii

Jeśli widzisz w logu:

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

to znaczy, że gdzieś leży plik socketu, do którego nie należy żaden proces. Najpierw upewnij się, że naprawdę nie działa żaden serwer, dopiero potem usuń plik:

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

Jeśli pgrep nadal pokazuje jakiś proces, nie kasuj pliku. Inaczej wszystkie działające aplikacje stracą swoje połączenie, a serwer przy kolejnym starcie założy plik na nowo, podczas gdy stary proces będzie żył dalej.

Przyczyna 2: serwer i aplikacja mają na myśli różne ścieżki

To ten przypadek, w którym wszystko działa, a mimo to nic nie idzie: ss -lx pokazuje /run/mysqld/mysqld.sock, ale aplikacja szuka pod /tmp/mysql.sock. Typowe powody to samodzielnie skompilowany serwer, przejście z MySQL na MariaDB, przeprowadzka z serwera z panelem na czysty system albo instalacja PHP z obcego repozytorium o innych ustawieniach domyślnych.

Czystą drogą jest wyrównanie ścieżki dokładnie w trzech miejscach. Po pierwsze po stronie serwera. Plik nazywa się przy każdej kombinacji inaczej: w Debianie i Ubuntu z MariaDB /etc/mysql/mariadb.conf.d/50-server.cnf, w Debianie i Ubuntu z MySQL /etc/mysql/mysql.conf.d/mysqld.cnf, a w AlmaLinux, Rocky Linux i Oracle Linux /etc/my.cnf.d/mariadb-server.cnf względnie /etc/my.cnf.d/mysql-server.cnf. Katalog /etc/mysql/ w rodzinie Red Hat w ogóle nie istnieje, tam wszystko idzie przez /etc/my.cnf i /etc/my.cnf.d/:

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

Po drugie dla narzędzi wiersza poleceń, w 50-client.cnf albo we własnym pliku:

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

Po trzecie dla PHP. Trzy wpisy w php.ini muszą zawierać tę samą ścieżkę, inaczej konfiguracja serwera nic nie da:

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

Który plik php.ini w ogóle obowiązuje, powie ci php --ini, o ile zainstalowany jest pakiet php-cli, w przeciwnym razie shell odpowie tylko php: command not found. Ważniejsze jest zastrzeżenie, które za tym stoi: php --ini podaje plik wiersza poleceń, a akurat ten w aplikacji webowej prawie nigdy nie jest winowajcą. Decydujący jest plik FPM, zwykle /etc/php/8.3/fpm/php.ini, a to, co tam faktycznie dociera, pokazuje php-fpm8.3 -i | grep -E 'Loaded Configuration|pdo_mysql.default_socket|mysqli.default_socket'. Po zmianie konieczny jest restart usługi FPM, a nie tylko reload serwera WWW. Jeśli aplikacja PHP nadal nic nie zwraca, kolejnym przystankiem jest często wpis Naprawa błędu nginx 502 Bad Gateway.

Przy aplikacjach, które mają ścieżkę wpisaną na sztywno i których nie możesz ruszyć, w ostateczności pomoże dowiązanie symboliczne:

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

To jednak nie przeżyje restartu, bo /tmp jest na wielu systemach czyszczony. Na stałe należy zapisać to w regule tmpfiles albo, jeszcze lepiej, w konfiguracji samej aplikacji.

Przyczyna 3: uprawnienia i brakujący katalog /run/mysqld

Jeśli dostajesz (13) Permission denied, socket istnieje, ale twój użytkownik się do niego nie dostaje. Sam socket ma zwykle uprawnienia 0777, więc dostęp rozbija się o katalog nadrzędny:

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

Drugi klasyk: /run to tmpfs, a więc po każdym restarcie jest pusty. Podkatalog /run/mysqld powstaje na nowo przy starcie, albo przez systemd-tmpfiles, albo przez skrypt startowy. Jeśli przy ręcznej instalacji odpowiednia reguła nigdy nie trafiła do systemu, serwer wystartuje dokładnie raz (dopóki katalog był założony ręcznie), a po kolejnym restarcie już nigdy. Załóż wtedy plik /etc/tmpfiles.d/mysql.conf:

d /run/mysqld 0755 mysql mysql -

Zastosujesz to bez restartu poleceniem systemd-tmpfiles --create. Kto prowadzi własny unit, może zamiast tego ustawić RuntimeDirectory=mysqld, zobacz Tworzenie usługi systemd.

Przyczyna 4: AppArmor i SELinux

Te dwa mechanizmy dają najbardziej mylący wariant błędu, bo uprawnienia w systemie plików wyglądają poprawnie, a serwer i tak zgłasza:

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

W Ubuntu pakiet MySQL dostarcza własny profil AppArmor. Jeśli przeniosłeś ścieżkę socketu w jakieś nietypowe miejsce, profil zabroni utworzenia pliku. Odmowy nie trafiają do logu MySQL, tylko tutaj:

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

Profil rozszerzysz w pliku /etc/apparmor.d/local/usr.sbin.mysqld, trafia tam wiersz w rodzaju /run/mysqld/mein.sock rw,, a potem systemctl reload apparmor. W AlmaLinux i Rocky Linux odpowiednikiem jest SELinux, tam sprawdzasz to poleceniem ausearch -m avc -ts recent i ustawiasz kontekst przez semanage fcontext oraz restorecon. W obu przypadkach wygodniejszą drogą jest po prostu zostawienie socketu w przewidzianym dla niego miejscu domyślnym.

Różnice między dystrybucjami w skrócie

Większość poradników podaje jedną ścieżkę dla wszystkich systemów. To nieprawda i właśnie na tym rozbija się kopiowanie cudzych rozwiązań. Stan na lipiec 2026:

Dwie rzeczy z tego są ważne. Po pierwsze: Debian nie dostarcza pakietu mysql-server, tam standardem jest MariaDB. apt install mysql-server na Debianie kończy się niepowodzeniem, a pasujące do tego poradniki z sieci prowadzą donikąd. Po drugie: w rodzinie Red Hat socket leży w katalogu danych, a nie w /run. Kto przenosi aplikację z Debiana na AlmaLinux i zabiera ścieżkę ze sobą, wyprodukuje ten błąd z żelazną pewnością.

Przypadek szczególny na marginesie: w kontenerach nie ma ani systemd, ani znanego z hosta katalogu /run/mysqld. Jeśli baza działa w kontenerze, a aplikacja obok, wspólnego socketu nie ma. Tam nie ma innej drogi niż TCP i nazwa kontenera w roli hosta.

Po czym poznasz, że problem naprawdę zniknął

systemctl start bez komunikatu błędu to jeszcze nie dowód. Sprawdź w tej kolejności:

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

Odpowiedź mysqld is alive z mysqladmin ping to właściwy certyfikat jakości, bo przychodzi przez ten sam socket, przez który idzie także twoja aplikacja. Potem próba kontrolna z warstwy aplikacji, czyli nie jako root, lecz jako użytkownik, na którym działa serwer WWW:

sudo -u www-data mysql -u twojuzytkownik -p twojabaza -e "SELECT 1"

I na koniec test restartu. Przerażająco duża część błędów socketu wraca po kolejnym restarcie, bo naprawa działała wyłącznie w czasie pracy systemu (katalog założony ręcznie, dowiązanie w /tmp, usługa nieaktywowana). Dlatego:

systemctl enable mariadb
systemctl is-enabled mariadb

Jeśli to możliwe, uruchom serwer raz całkowicie od nowa i powtórz cztery polecenia kontrolne. Na serwerze root w KernelHoście trwa to niecałą minutę i oszczędza ci powtórki tego błędu o trzeciej nad ranem.

Gdy naprawa idzie nie tak

Trzy sytuacje, w których ludzie regularnie utykają.

Serwer po zmianie konfiguracji w ogóle nie startuje. Literówka w pliku .cnf prowadzi do natychmiastowego przerwania, często z komunikatem unknown variable. Składnię da się sprawdzić bez uruchamiania usługi, ale polecenie zależy od serwera:

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

Pierwszy wiersz dotyczy wyłącznie MySQL 8. --validate-config to opcja czysto MySQL-owa i nie istnieje w żadnej wersji MariaDB, sprawdzone od 10.5 do 11.8. MariaDB odpowiada zamiast tego komunikatem [ERROR] mysqld: unknown option '--validate-config', a po nim [ERROR] Aborting, przy czym w rodzinie Red Hat ten komunikat nie pojawia się nawet na terminalu, tylko w logu błędów: polecenie działa tam zupełnie po cichu. Również --user=mysql jest obowiązkowe, a nie ozdobne, bo wywołany jako root MySQL 8 przerywa jeszcze wcześniej komunikatem Please consult the Knowledge Base to find out how to run mysqld as root!. Dla MariaDB nie ma odpowiednika --validate-config. Tam drugi wiersz pokazuje, jakie opcje serwer w ogóle zna, a my_print_defaults mysqld mariadbd pokazuje, co faktycznie odczytuje z twoich plików.

Przed każdą zmianą zachowaj kopię, wtedy droga powrotna to jedno cp. Zwróć poza tym uwagę, do którego pliku piszesz: w Debianie i Ubuntu pliki w conf.d są wczytywane alfabetycznie, a późniejszy wpis nadpisuje wcześniejszy.

Nie możesz się już dostać jako root. W MariaDB na Debianie i Ubuntu dla root@localhost domyślnie ustawione jest uwierzytelnianie przez unix_socket. Oznacza to, że sudo mysql działa bez hasła, a mysql -u root -p jako zwykły użytkownik już nie, i to z komunikatem ERROR 1698 (28000): Access denied for user 'root'@'localhost'. To nie jest problem z socketem, tylko zamierzone zachowanie.

Skasowałeś plik socketu przy działającym serwerze. Proces pracuje dalej, trzyma skasowany inode i przez ścieżkę nie jest już osiągalny. Pliku nie da się utworzyć ręcznie, socket powstaje wyłącznie przez bind() wykonane przez proces. Tutaj pomoże tylko czysty restart usługi. Dopóki go nie ma, dosięgniesz serwera przez TCP z --protocol=TCP, o ile nie jest ustawione skip-networking. Wykorzystaj to okno czasowe na zrzut najważniejszych baz danych, zanim uruchomisz usługę ponownie.

Ostatnia uwaga co do kolejności: nigdy nie zmieniaj kilku rzeczy naraz. Najpierw status usługi, potem porównanie ścieżek, na końcu uprawnienia. Kto równolegle rusza my.cnf, php.ini i uprawnienia plików, potem nie wie, co pomogło, i następnym razem zaczyna od zera. Jeśli stawiasz system od nowa i chcesz uniknąć takich pułapek od samego początku, pomoże Lista kontrolna nowego serwera root, a dla kompletnego stosu bazodanowego z interfejsem webowym wpis Instalacja Apache, PHP, MySQL i phpMyAdmin na Debianie.