Cannot Connect to the Docker Daemon Hatası: Teşhis ve Çözüm Adımları

Hata mesajını doğru okumak

Belgelerdeki sorun giderme sayfası hatayı şu biçimde gösterir:

Cannot connect to the Docker daemon. Is 'docker daemon' running on this host?

Docker Desktop for Linux belgelerinde aynı sorunun soket yolunu da içeren bir biçimi geçer: Cannot connect to the Docker daemon at unix:///var/run/docker.sock. Is the docker daemon running? Mesajdaki unix:///var/run/docker.sock kısmı çok değerlidir, çünkü CLI'nin tam olarak hangi adrese bağlanmaya çalıştığını gösterir. Adres beklediğiniz yer değilse sorun daemon'da değil istemci ayarındadır.

Bir ayrımı baştan yapmak zaman kazandırır. Daemon çalışıyor ama kullanıcınızın sokete erişim yetkisi yoksa CLI "permission denied" der; bu durumda sudo docker info çalışır, docker info çalışmaz. Daemon hiç çalışmıyorsa her ikisi de bağlantı hatası verir.

1. Adım: Daemon çalışıyor mu?

Belgelere göre Docker'ın çalıştığını işletim sisteminden bağımsız biçimde kontrol etmenin yolu Docker'ın kendisine sormaktır: docker info. Ayrıca işletim sistemi araçlarını da kullanabilirsiniz:

docker info

sudo systemctl is-active docker
sudo service docker status

ps aux | grep dockerd

docker info başarılıysa daemon çalışıyor ve CLI ona ulaşabiliyor demektir. systemctl is-active docker servisin durumunu verir. Son olarak süreç listesinde dockerd sürecini ps veya top ile arayabilirsiniz. Servis durmuşsa başlatın; belgeler Ubuntu ve Debian gibi sistemlerde servisin otomatik başladığını, elle başlatmak için şu komutu verir:

sudo systemctl start docker

Fedora, RHEL ve CentOS'ta kurulum Docker'ı başlatmaz; servisi hiç başlatmadıysanız bağlantı hatası çok olasıdır. Açılışta da başlaması için sudo systemctl enable --now docker kullanın. Ayrıntılar Debian, Fedora, RHEL ve CentOS kurulumu yazısında.

2. Adım: İstemci nereye bağlanıyor?

Daemon çalıştığı halde hata alıyorsanız istemci yanlış adrese gidiyor olabilir. Belgeler önce DOCKER_HOST ortam değişkenine bakmanızı söyler:

env | grep DOCKER_HOST

# Yanlışlıkla ayarlandıysa:
unset DOCKER_HOST

Komut bir değer döndürüyorsa CLI o hosttaki daemon'a bağlanmaya ayarlıdır; boşsa yerel daemon'a bağlanır. Değişken hatalıysa unset ile kaldırın ve yeniden ayarlanmaması için ~/.bashrc veya ~/.profile gibi dosyaları kontrol edin. DOCKER_HOST bilerek ayarlandıysa uzak hostta daemon'ın çalıştığını ve bir güvenlik duvarının veya ağ kesintisinin bağlantıyı engellemediğini doğrulamanız gerekir.

İkinci yer Docker context'idir. Context belgelerine göre docker context ls çıktısında yıldızla işaretli context aktif olandır ve tüm komutlar ona gider; bu seçim DOCKER_HOST ve DOCKER_CONTEXT ortam değişkenleriyle veya --context ve --host bayraklarıyla geçersiz kılınabilir. Varsayılan context yerel /var/run/docker.sock soketine bağlanır. Daha önce uzak bir sunucu için context oluşturup docker context use ile seçtiyseniz komutlarınız o sunucuya gidiyordur. Context yönetimi Docker context ile uzak sunucu yönetimi yazısında.

Docker Desktop for Linux kullanan makinelerde durum biraz farklıdır: Desktop, sistem genelindeki /var/run/docker.sock yerine kullanıcıya özel ~/.docker/desktop/docker.sock soketini kullanır. CLI bunu desktop-linux context'iyle otomatik çözer, ancak doğrudan sokete bağlanan SDK'lar ve araçlar DOCKER_HOST ayarlanmadan /var/run/docker.sock adresine gider ve yukarıdaki hatayı verir.

3. Adım: Daemon başlamıyorsa loglara bakın

Servis başlatılamıyorsa nedeni daemon loglarındadır. Linux'ta belgelerin verdiği komut şudur; dağıtıma göre /var/log/syslog veya /var/log/messages dosyaları da kullanılabilir:

journalctl -xu docker.service

Daha eski Linux sistemlerinde loglar /var/log/messages, /var/log/daemon.log veya /var/log/docker.log dosyalarında olabilir. Sorunu canlı görmek isterseniz servis yerine daemon'ı bir kez elle, ön planda başlatabilirsiniz; bu durumda loglarını doğrudan terminale yazar ve Ctrl+C ile durur. Belgelerdeki örnek çıktı şöyledir:

dockerd

INFO[0000] +job init_networkdriver()
INFO[0000] +job serveapi(unix:///var/run/docker.sock)
INFO[0000] Listening for HTTP on unix (/var/run/docker.sock)

Bu yöntemin bir dezavantajı vardır: belgelere göre elle başlatılan daemon, sistem başlangıç betiklerinin kurduğu ortamdan farklı bir ortamla çalışabilir ve bu, hata ayıklamayı zorlaştırabilir. Kalıcı teşhis için debug modu daha güvenli bir yoldur.

Debug modunu açmak

Belgelerin önerdiği yol daemon.json içinde debug anahtarını true yapmaktır; bu yöntem her Docker platformunda çalışır. Dosya boşsa şu içerik yeterlidir:

{
  "debug": true
}

Dosyada başka anahtarlar varsa yalnızca "debug": true satırını ekleyin ve son satır değilse sonuna virgül koymayı unutmayın. log-level anahtarı tanımlıysa info veya debug olduğundan emin olun; varsayılan info'dur ve geçerli değerler debug, info, warn, error, fatal'dır. Ardından daemon'a yapılandırmayı yeniden yüklemesi için HUP sinyali gönderin:

sudo kill -SIGHUP $(pidof dockerd)

Daemon yanıt vermiyorsa ve takıldığı yeri görmek istiyorsanız SIGUSR1 sinyaliyle tüm goroutine ve iş parçacıklarının yığın izini (stack trace) loga yazdırabilirsiniz. Bu daemon'ı durdurmaz; daemon sinyali işledikten sonra çalışmaya devam eder. Loglarda goroutine stacks written to /var/run/docker/goroutine-stacks-...log biçiminde, izin yazıldığı dosyanın yolunu gösteren bir satır görürsünüz.

sudo kill -SIGUSR1 $(pidof dockerd)

Yapılandırma çakışması: daemon.json ile bayraklar

Daemon'ın başlamamasının en tipik nedenlerinden biri, aynı seçeneğin hem daemon.json dosyasında hem de başlatma bayraklarında verilmesidir. Belgelerdeki örnek hata şöyledir:

unable to configure the Docker daemon with file /etc/docker/daemon.json:
the following directives are specified both as a flag and in the configuration
file: hosts: (from flag: [unix:///var/run/docker.sock], from file: [tcp://127.0.0.1:2376])

Bu örnekteki hosts çakışması özellikle sık görülür. Debian ve Ubuntu'da systemd servisi dockerd'yi her zaman bir -H bayrağıyla başlatır; dosyaya ayrıca hosts yazarsanız çakışma oluşur ve daemon başlamaz. Belgelerin geçici çözümü, varsayılan -H argümanını kaldıran bir systemd ek dosyası oluşturmaktır. /etc/systemd/system/docker.service.d/docker.conf dosyasının içeriği şöyledir:

[Service]
ExecStart=
ExecStart=/usr/bin/dockerd

Ardından sudo systemctl daemon-reload çalıştırıp Docker'ı başlatırsınız. Belgeler bir uyarı ekler: bu geçersiz kılmayı yapıp daemon.json içinde bir hosts girdisi tanımlamazsanız Docker başlamaz. Daemon'ı ağa açmanın güvenlik tarafı ayrı ve önemli bir konudur: Docker daemon uzak erişim, SSH ve TLS. Dosyanın genel yapısı ise daemon.json yapılandırma yazısında.

Güvenlik duvarı ve iptables kaynaklı başlatma hataları

Fedora kurulum sayfası özel bir durumu anlatır: servis başlamazsa ve journalctl -u docker çıktısında failed to find iptables görürseniz iptables komutunu alternatives ile iptables-nft'ye yönlendirip servisi yeniden başlatmanız gerekir (sudo alternatives --set iptables /usr/bin/iptables-nft).

Engine 29.0.0 ile deneysel olarak gelen nftables arka ucunu (firewall-backend) etkinleştirdiyseniz sürüm notlarındaki bir değişikliği bilmelisiniz: bu modda Docker host üzerinde IP yönlendirmeyi kendisi açmaz. Bir bridge ağı yönlendirmeye ihtiyaç duyuyor ama yönlendirme kapalıysa daemon başlangıcı veya ağ oluşturma hatayla başarısız olur. Notlar iki seçenek sunar: yönlendirmeyi açıp Docker dışı arayüzler arasında istenmeyen yönlendirmeyi engelleyen kuralları kurmak ya da --ip-forward=false ile kontrolü kapatmak; ikinci durumda port yönlendirme dahil bazı bridge özellikleri çalışmayabilir. Güvenlik duvarı tarafı Docker, iptables ve UFW yazısında.

Çekirdek, cgroup ve bellek uyarıları

Belgelere göre çekirdeğiniz 3.10'dan eskiyse veya gerekli çekirdek modülleri eksikse Docker düzgün çalışamaz. Uyumluluğu kontrol etmek için Docker deposundaki check-config.sh betiğini indirip çalıştırabilirsiniz; betik yalnızca Linux'ta çalışır:

curl https://raw.githubusercontent.com/docker/docker/master/contrib/check-config.sh > check-config.sh
bash ./check-config.sh

Ubuntu veya Debian'da imajlarla çalışırken WARNING: Your kernel does not support swap limit capabilities. Limitation discarded. uyarısını görebilirsiniz. Belgeler bu yeteneklere ihtiyacınız yoksa uyarıyı yok sayabileceğinizi söyler. Açmak isterseniz /etc/default/grub dosyasındaki GRUB_CMDLINE_LINUX satırına cgroup_enable=memory swapaccount=1 eklenir, sudo update-grub çalıştırılır ve sistem yeniden başlatılır. Belgeler bunun bir bedeli olduğunu da yazar: bellek ve swap muhasebesi, Docker çalışmıyorken bile toplam belleğin yaklaşık yüzde 1'i kadar ek yük ve genel olarak yüzde 10 performans düşüşü getirir.

Engine 29.0.0 notlarına göre cgroup v1 kullanımdan kaldırılma (deprecated) sürecindedir; desteğin en az Mayıs 2029'a kadar süreceği, ancak bir an önce cgroup v2'ye geçilmesi gerektiği belirtilir. Container'lar sistemin sahip olduğundan fazla bellek kullanmaya çalışırsa çekirdeğin OOM killer'ı bir container'ı veya Docker daemon'ının kendisini durdurabilir; belgeler yeterli belleğe sahip hostlar kullanmanızı ve bellek riskleri bölümünü okumanızı önerir. Limit ayarları için Docker CPU ve bellek limiti yazısına bakın.

Ağ sorunları: DNS, IP yönlendirme ve kaybolan ağlar

Daemon çalıştığı halde container'lar ağa çıkamıyorsa belgelerdeki ağ bölümü üç tipik sorunu listeler.

• DNS çözümleme uyarısı: masaüstü dağıtımlarda ağ yöneticisi /etc/resolv.conf dosyasına 127.0.0.1 gibi bir loopback adresinde çalışan dnsmasq yazabilir. Container kendi ağ ad alanında olduğu için bu adres container'ın kendisini gösterir. Docker bunu fark ederse dış DNS sunucularına (8.8.8.8, 8.8.4.4) döndüğünü bildiren bir uyarı yazar. İç ağdaki adları çözmeniz gerekiyorsa daemon.json içinde dns anahtarıyla DNS sunucusu verebilir veya dnsmasq'ı kapatabilirsiniz.
• IP yönlendirme: ağı systemd 219 veya sonrasıyla systemd-network üzerinden elle yapılandırdıysanız, systemd 220'den itibaren arayüz bazlı yönlendirme ayarı varsayılan olarak kapalıdır ve container'lar ağa erişemeyebilir. Belgeler RHEL, CentOS ve Fedora için ilgili .network dosyasının [Network] bölümüne IPForward=kernel veya IPForward=true eklemeyi önerir.
• Kaybolan Docker ağları: docker0 köprüsü veya özel bir ağ rastgele kayboluyorsa hosttaki başka bir ağ aracı Docker arayüzlerine müdahale ediyor olabilir. Belgeler netscript kuruluysa kaldırmayı, NetworkManager veya systemd-networkd'de Docker arayüzlerini (docker0, br-*, veth*) yönetilmeyen olarak işaretlemeyi ve cloud-init ile Netplan kullanan sistemlerde özel bir Netplan yapılandırması uygulamayı önerir.

DNS için daemon.json örneği belgelerde şöyledir; değişiklikten sonra daemon yeniden başlatılır. İç DNS sunucunuz genel adları çözemiyorsa listeye bunu yapabilen en az bir sunucu ekleyin, aksi halde Docker Hub'a da bağlanamazsınız:

{
  "dns": ["8.8.8.8", "8.8.4.4"]
}

Bridge ağlarının ad çözümlemesi ve ağ sürücüleri Docker bridge network ile Docker network türleri yazılarında ayrıntılı anlatılıyor.

Volume sorunu: Unable to remove filesystem

Belgelerdeki son örnek, container silerken alınan Error: Unable to remove filesystem hatasıdır. Google cAdvisor gibi bazı araçlar /var/lib/docker/ dizinini kendi container'larına bağlar. Bu, diğer tüm container'ların kaynaklarını o container içinde dosya sistemi olarak bağlamak anlamına gelir; o container dosya tanıtıcılarını kapatmazsa diğer container'ları silmek "Device or resource busy" hatasıyla başarısız olabilir. Belgeler /var/lib/docker dizinini bu şekilde bağlamamanızı önerir; hangi sürecin yolu meşgul ettiğini lsof ile bulabilir, geçici çözüm olarak o dizini bağlayan container'ı durdurup silme işlemini yeniden deneyebilirsiniz.

Belirtiden çözüme hızlı tablo

Sık Sorulan Sorular

sudo docker çalışıyor, docker çalışmıyor; daemon mı bozuk?

Hayır, bu durumda daemon çalışıyordur. Sorun kullanıcınızın Docker soketine erişim izninin olmamasıdır. Çözüm ve güvenlik etkisi için sudo olmadan Docker yazısına bakın.

Sunucu yeniden başladıktan sonra hata alıyorum, neden?

Docker servisi açılışta başlayacak şekilde etkinleştirilmemiş olabilir. Debian ve Ubuntu'da bu varsayılandır; diğer dağıtımlarda sudo systemctl enable docker.service ve sudo systemctl enable containerd.service gerekir. Container'ların da otomatik başlaması için restart policy ayarlayın.

Daemon tamamen donmuş görünüyor, ne yapabilirim?

sudo kill -SIGUSR1 $(pidof dockerd) ile daemon'ı durdurmadan yığın izini loga yazdırabilir ve hangi işlemde takıldığını görebilirsiniz. Belgelere göre bu izler, daemon içindeki tüm goroutine ve iş parçacıklarının durumunu gösterir.

Hata disk dolmasından kaynaklanıyor olabilir mi?

Belgelerin sorun giderme sayfası disk dolmasını ayrı bir başlık olarak ele almaz. Disk kullanımını kontrol etmek ve kullanılmayan imaj, container ve volume'ları temizlemek için Docker prune ile disk temizleme, log dosyalarının büyümesini önlemek için Docker log boyutunu sınırlama yazılarına bakın.

Marka adları sahiplerine aittir. Bu yazı bağımsız bir teknik rehberdir; adı geçen kuruluşlarla bayilik veya ortaklık ilişkisi bulunduğu anlamına gelmez.

İlgili içerikler: Docker öğrenme rehberi · permission denied · daemon.json yapılandırma · Docker context · Docker ve UFW · Linux loglarını okuma