7 Error Docker Paling Sering Muncul & Cara Mengatasinya (Lengkap)

Docker sudah jadi standar untuk menjalankan aplikasi modern, tapi pesan error-nya sering bikin bingung — apalagi kalau baru pertama kali ketemu. Kabar baiknya, sebagian besar error Docker itu-itu saja polanya. Artikel ini merangkum 7 error Docker paling sering muncul lengkap dengan arti pesannya, penyebabnya, perintah perbaikan yang sudah terverifikasi, dan cara mencegahnya terulang.

Untuk setiap error, ikuti pola troubleshooting yang sama: baca pesan error → cek log → inspect → perbaiki → cegah. Semua perintah di bawah sudah diverifikasi sintaksnya terhadap dokumentasi resmi Docker.

Pola Umum: Cara Membaca Pesan Error Docker

Sebelum masuk ke daftar error, pahami dulu anatomi pesan error Docker. Hampir semua pesan mengikuti format Error response from daemon: ... diikuti penjelasan spesifik. Kata kunci pertamanya biasanya sudah cukup untuk menebak kategori masalah: permission denied berarti soal hak akses, Bind for ... failed berarti soal jaringan/port, dan pull access denied berarti soal autentikasi registry.

Dua perintah adalah sahabat terbaikmu dalam setiap investigasi. docker logs nama-container menampilkan apa yang dikatakan aplikasi di dalam container — seringkali akar masalahnya ada di sana, bukan di Docker-nya. Sedangkan docker inspect nama-container membongkar seluruh state container (exit code, status OOM, jumlah restart, konfigurasi network) dalam format JSON yang bisa difilter. Biasakan menjalankan keduanya sebelum mengubah konfigurasi apa pun, supaya kamu memperbaiki penyebabnya, bukan gejalanya.

1. permission denied saat menjalankan perintah Docker

Pesan error yang muncul:

Got permission denied while trying to connect to the Docker daemon socket
at unix:///var/run/docker.sock: dial unix /var/run/docker.sock:
connect: permission denied

Artinya: user Linux kamu tidak punya izin mengakses socket Docker (/var/run/docker.sock). Socket ini dimiliki oleh user root dan grup docker — kalau akunmu belum masuk grup tersebut, setiap perintah docker tanpa sudo akan ditolak.

Cara memperbaiki:

# Tambahkan user saat ini ke grup docker
sudo usermod -aG docker $USER

# Aktifkan keanggotaan grup tanpa logout (atau logout lalu login ulang)
newgrp docker

# Tes: perintah ini harus berjalan tanpa sudo dan tanpa error
docker run --rm hello-world

Catatan keamanan: anggota grup docker secara efektif setara root (bisa me-mount seluruh filesystem host ke container). Jadi hanya tambahkan user yang kamu percaya.

Pencegahan: tambahkan user ke grup docker segera setelah instalasi Docker selesai, sebelum mulai bekerja. Di server yang dikelola tim, langkah ini sebaiknya masuk ke skrip provisioning (Ansible, cloud-init) supaya tidak ada yang tergoda memakai sudo docker untuk semua hal.

2. port is already allocated

Pesan error yang muncul:

Error response from daemon: driver failed programming external connectivity
on endpoint webku: Bind for 0.0.0.0:8080 failed: port is already allocated

Artinya: port host yang kamu minta (di contoh ini 8080) sudah dipakai — entah oleh container lain atau oleh proses di host itu sendiri.

Cara mendiagnosis:

# Cek container apa saja yang sedang berjalan dan mapping port-nya
docker ps --format 'table {{.Names}}\t{{.Ports}}'

# Cek proses host yang memakai port 8080 (pilih salah satu)
sudo ss -tlnp | grep 8080
sudo lsof -i :8080

Cara memperbaiki: ada dua pilihan — hentikan yang memakai port, atau pakai port lain.

# Pilihan A: hentikan container yang memakai port tersebut
docker stop nama-container

# Pilihan B: petakan ke port host yang berbeda (8081 di host -> 8080 di container)
docker run -d -p 8081:8080 --name webku nginx

Pencegahan: dokumentasikan alokasi port untuk setiap service, dan di Docker Compose selalu tulis mapping port secara eksplisit agar tabrakan mudah terdeteksi.

3. Cannot connect to the Docker daemon

Pesan error yang muncul:

Cannot connect to the Docker daemon at unix:///var/run/docker.sock.
Is the docker daemon running?

Artinya: Docker client tidak bisa menghubungi Docker daemon — biasanya karena daemon memang belum berjalan, atau client mengarah ke alamat daemon yang salah.

Cara memperbaiki:

# 1. Cek status daemon
sudo systemctl status docker

# 2. Jalankan daemon jika belum aktif
sudo systemctl start docker

# 3. Agar otomatis jalan setiap boot
sudo systemctl enable docker

# 4. Pastikan variabel DOCKER_HOST tidak mengarah ke tempat yang salah
echo $DOCKER_HOST
# Jika isinya aneh, kosongkan:
unset DOCKER_HOST

Pengguna Docker Desktop (Windows/Mac): error ini biasanya berarti aplikasinya belum dibuka — cukup jalankan Docker Desktop dan tunggu ikonnya stabil. Di Windows, pastikan juga backend WSL 2 sudah aktif.

Pencegahan: aktifkan service Docker saat boot (systemctl enable docker) di server, supaya tidak perlu start manual setiap restart.

4. no space left on device

Pesan error yang muncul:

failed to copy files: write /var/lib/docker/tmp/...: no space left on device

Pesan ini bisa muncul saat docker pull, docker build, atau menjalankan container. Artinya: disk yang dipakai Docker penuh. Biang keroknya biasanya bertumpuk: image lama yang tak terpakai, container yang sudah berhenti, build cache, atau file log container yang membengkak tanpa rotasi.

Cara mendiagnosis:

# Lihat ke mana saja disk Docker terpakai
docker system df

# Lihat kondisi disk host secara umum
df -h /var/lib/docker

Cara memperbaiki — lakukan dari yang paling aman dulu:

# 1. Hapus container yang sudah berhenti (aman)
docker container prune

# 2. Hapus image yang tidak terpakai / dangling (aman)
docker image prune

# 3. Hapus build cache (aman, hanya memperlambat build berikutnya)
docker builder prune

Kalau masih kurang, barulah pakai perintah besar — dengan peringatan:

# HAPUS semua objek Docker yang tidak terpakai (image, container, network, cache)
docker system prune -a

⚠️ Peringatan: jangan asal menjalankan docker system prune -a --volumes. Flag --volumes menghapus volume — termasuk volume berisi data database yang container-nya sedang berhenti. Itu bisa jadi insiden kehilangan data.

Pencegahan permanen — batasi ukuran log container lewat /etc/docker/daemon.json:

{
  "log-driver": "json-file",
  "log-opts": {
    "max-size": "10m",
    "max-file": "3"
  }
}

Setelah itu restart daemon (sudo systemctl restart docker). Tambahkan juga jadwal prune rutin, misal mingguan via cron.

5. pull access denied

Pesan error yang muncul:

Error response from daemon: pull access denied for myapp/backend,
repository does not exist or may require 'docker login':
denied: requested access to the resource is denied

Artinya: Docker tidak boleh mengunduh image tersebut. Penyebabnya tiga kemungkinan: (1) repository bersifat privat dan kamu belum login, (2) salah ketik nama image atau tag, (3) akunmu memang tidak diberi akses ke repository itu.

Cara memperbaiki:

# 1. Login ke registry (Docker Hub)
docker login

# 2. Periksa ejaan nama image dan tag-nya — satu huruf salah saja gagal
docker pull nama-image-yang-benar:tag

# 3. Kalau tetap ditolak setelah login, berarti akunmu tidak punya akses:
#    minta pemilik repository menambahkan akunmu sebagai collaborator

Pencegahan: di pipeline CI/CD, lakukan docker login memakai kredensial dari secret manager (jangan hardcode password di script), dan selalu pin tag image yang spesifik alih-alih latest.

6. exec format error (image ARM vs x86)

Pesan error yang muncul:

exec /usr/local/bin/docker-entrypoint.sh: exec format error

Artinya: binary di dalam image dikompilasi untuk arsitektur CPU yang berbeda dari mesin yang menjalankannya. Kasus klasik: image di-build di Mac Apple Silicon (ARM64), lalu dijalankan di server Linux x86 (AMD64) — atau sebaliknya.

Cara mendiagnosis:

# Arsitektur image vs arsitektur daemon — harus cocok
docker image inspect nama-image --format '{{.Os}}/{{.Architecture}}'
docker version --format '{{.Server.Os}}/{{.Server.Arch}}'

Cara memperbaiki:

# Jalankan image untuk platform tertentu (bisa lambat karena emulasi QEMU)
docker run --platform linux/amd64 nama-image

# Build ulang image untuk arsitektur target
docker build --platform linux/amd64 -t myapp .

# Solusi permanen: build satu image multi-arsitektur
docker buildx build --platform linux/amd64,linux/arm64 -t myapp --push .

Catatan: kalau arsitektur sudah cocok tapi error tetap muncul, periksa entrypoint script-nya — file tanpa shebang (#!/bin/sh) di baris pertama atau file berekstensi Windows (CRLF) juga memicu exec format error.

Pencegahan: selalu tentukan --platform secara eksplisit di pipeline CI/CD sesuai target deploy.

7. Container restart terus / exit code 137 (OOM)

Gejala: docker ps menampilkan status Restarting (137) berulang-ulang, atau container mati lalu hidup lagi tanpa henti.

Artinya: exit code 137 = 128 + 9, yaitu proses dibunuh sinyal SIGKILL. Penyebab paling umum: OOM killer — container memakai memori melebihi batasnya sehingga kernel mematikannya.

Cara mendiagnosis:

# Konfirmasi: apakah benar dibunuh OOM killer?
docker inspect nama-container --format \
  'exit={{.State.ExitCode}} oom={{.State.OOMKilled}} restarts={{.RestartCount}}'

# Lihat pemakaian memori real-time
docker stats --no-stream

# Jejak OOM killer di log kernel
dmesg -T | grep -i 'killed process'

Jika oom=true, berarti limit memori memang terlampaui. Bedakan dua polanya: memori naik terus tanpa pernah stabil = memory leak di aplikasi; memori stabil tapi di atas limit = limit-nya saja yang kekecilan.

Cara memperbaiki:

# Naikkan limit memori container (contoh: 1 GB)
docker run -d --memory=1g --name appku myapp

Catatan runtime: JVM dan Node.js versi lama membaca memori host, bukan limit container — sehingga heap-nya bisa diset untuk mesin 64 GB di dalam container 512 MB dan pasti kena OOM. Set eksplisit: JVM dengan -XX:MaxRAMPercentage=75.0, Node.js dengan --max-old-space-size.

Pencegahan: tetapkan limit memori yang realistis untuk setiap service, pantau dengan docker stats, dan pasang alert pada RestartCount.

Tabel Ringkas: Gejala → Perintah Pertama

Gejala	Perintah pertama yang dijalankan
permission denied	sudo usermod -aG docker $USER lalu newgrp docker
port is already allocated	docker ps + sudo ss -tlnp | grep PORT
Cannot connect to the Docker daemon	sudo systemctl start docker
no space left on device	docker system df lalu prune bertahap
pull access denied	docker login, cek ejaan nama image
exec format error	docker image inspect ... --format '{{.Architecture}}'
Restart loop / exit 137	docker inspect ... --format '{{.State.OOMKilled}}'

Kesimpulan

Tujuh error di atas mencakup sebagian besar masalah Docker yang ditemui sehari-hari — dari izin akses, port, daemon, disk, autentikasi, arsitektur CPU, sampai kehabisan memori. Kuncinya selalu sama: jangan panik membaca pesan error, salin pesan persisnya, lalu telusuri dengan docker logs dan docker inspect sebelum mengubah apa pun. Dengan pola pikir itu, troubleshooting Docker berubah dari tebak-tebakan jadi proses yang sistematis.

Kalau kamu sering berkutat dengan container, simpan tabel ringkas di atas sebagai contekan — ia akan menghemat banyak waktu debugging di kemudian hari.