Docker sangat membantu developer dalam membuat environment aplikasi yang konsisten. Dengan Docker, aplikasi bisa dijalankan di laptop lokal, server staging, maupun production dengan konfigurasi yang relatif sama. Developer tidak perlu menginstall semua dependency langsung di sistem operasi utama karena aplikasi berjalan di dalam container.
Namun, Docker juga sering menimbulkan error yang membingungkan, terutama untuk pemula. Container bisa tiba-tiba berhenti, port bentrok, build image gagal, volume tidak terbaca, permission file bermasalah, network antar-container tidak terkoneksi, Docker daemon tidak berjalan, hingga Docker Compose gagal membaca konfigurasi.
Artikel ini membahas error Docker secara lengkap, mulai dari Container Exited, Permission Denied, Port Already Allocated, Build Failed, Docker Daemon Error, Compose Error, Volume Missing, Bind Mount Error, Too Many Layers, Disk Full, Image Pull Failed, DNS Error, Network Bridge Error, Healthcheck Failed, Restart Loop, hingga Multi-stage Build Error.
Tujuannya bukan hanya memperbaiki error ketika terjadi, tetapi juga memahami penyebab dan cara mencegahnya agar workflow development dan deployment menjadi lebih stabil.
Sebelum masuk ke daftar error, penting untuk memahami bahwa Docker bekerja dengan beberapa komponen sekaligus:
Image: template berisi sistem file dan instruksi aplikasi.
Container: instance berjalan dari sebuah image.
Dockerfile: file instruksi untuk membangun image.
Volume: penyimpanan data yang tetap ada meskipun container dihapus.
Network: jalur komunikasi antar-container.
Docker daemon: service utama yang menjalankan Docker.
Docker Compose: alat untuk menjalankan banyak container dengan satu file konfigurasi.
Ketika salah satu komponen tersebut salah konfigurasi, error dapat muncul. Misalnya, aplikasi di dalam container gagal start karena environment variable tidak lengkap. Port container tidak bisa dibuka karena sudah dipakai service lain. Volume tidak terbaca karena path host salah. Build gagal karena dependency tidak tersedia. Network gagal karena service name tidak cocok.
Kunci troubleshooting Docker adalah membaca log, mengecek status container, memahami mapping port, memeriksa Dockerfile, memeriksa
docker-compose.yml
, dan memastikan resource server cukup.
1. Container Exited
Container Exited adalah kondisi ketika container sudah dibuat tetapi tidak lagi berjalan. Statusnya biasanya terlihat seperti
Exited (0)
,
Exited (1)
, atau kode lain saat menjalankan perintah:
docker ps -a
Penyebab
Container bisa berhenti karena beberapa alasan:
Proses utama di container selesai.
Aplikasi crash saat start.
Command atau entrypoint salah.
Environment variable kurang.
File konfigurasi tidak ditemukan.
Dependency aplikasi belum terinstall.
Port internal aplikasi salah.
Database atau service lain belum siap.
Container memang menjalankan task sekali jalan, bukan service long-running.
Contoh paling umum: container berbasis Node.js menjalankan
npm start
, tetapi script
start
tidak ada di
package.json
. Akibatnya, proses utama gagal dan container langsung berhenti.
Solusi
Cek status container:
docker ps -a
Lihat log container:
docker logs nama_container
Jika ingin melihat log real-time:
docker logs -f nama_container
Masuk ke container yang masih berjalan:
docker exec -it nama_container sh
Jika container langsung mati dan sulit diperiksa, jalankan image dengan shell:
docker run -it –entrypoint sh nama_image
Cek command yang dijalankan container:
docker inspect nama_container
Perhatikan bagian
Cmd
,
Entrypoint
,
Env
, dan
State
.
Contoh Perbaikan
Jika Dockerfile berisi:
CMD [“npm”, “start”]
Pastikan
package.json
memiliki script:
{ “scripts”: { “start”: “node server.js” } }
Jika aplikasi membutuhkan environment variable:
docker run -e APP_ENV=production -e DB_HOST=mysql nama_image
Atau dengan Compose:
services: app: environment: APP_ENV: production DB_HOST: mysql
Cara Mencegah
Pastikan proses utama container berjalan terus untuk aplikasi server.
Jangan menjalankan perintah sekali selesai jika container dimaksudkan sebagai service.
Tambahkan log aplikasi yang jelas saat startup.
Validasi environment variable saat aplikasi mulai.
Gunakan
depends_on
di Docker Compose jika container bergantung pada service lain, tetapi tetap tambahkan mekanisme retry karena
depends_on
tidak selalu menunggu service benar-benar siap.
2. Permission Denied
Error Permission Denied sering terjadi ketika container tidak punya izin membaca atau menulis file tertentu.
Penyebab
Penyebab umum:
File di host dimiliki user berbeda.
Bind mount mengarah ke folder yang tidak bisa ditulis.
Container berjalan sebagai user non-root.
Script tidak memiliki permission execute.
Docker daemon tidak bisa mengakses path tertentu.
SELinux/AppArmor membatasi akses.
Socket Docker tidak bisa diakses oleh user.
Contoh error:
permission denied
Atau:
EACCES: permission denied, open ‘/app/storage/logs/app.log’
Solusi
Cek permission file di host:
ls -la
Ubah permission script:
chmod +x entrypoint.sh
Jika folder perlu ditulis aplikasi:
chmod -R 775 storage
Atur owner sesuai UID/GID yang digunakan container:
chown -R 1000:1000 ./storage
Jika user lokal tidak bisa menjalankan Docker tanpa
sudo
, tambahkan user ke group Docker:
sudo usermod -aG docker $USER
Lalu logout dan login ulang.
Untuk sistem dengan SELinux, bind mount kadang perlu opsi tambahan:
docker run -v /path/host:/app/data:Z nama_image
Contoh Perbaikan di Dockerfile
Jika ingin menjalankan aplikasi sebagai user non-root:
RUN addgroup -S app && adduser -S app -G app RUN chown -R app:app /app USER app
Namun, pastikan folder yang perlu ditulis sudah dimiliki user tersebut.
Cara Mencegah
Hindari menjalankan container production sebagai root jika tidak perlu.
Samakan UID/GID antara host dan container untuk development.
Tentukan folder writable secara eksplisit.
Jangan memberi permission
777
sembarangan.
Gunakan volume named Docker untuk data yang tidak perlu langsung diedit dari host.
3. Port Already Allocated
Error Port Already Allocated terjadi ketika port host yang ingin dipakai Docker sudah digunakan proses lain.
Contoh error:
Bind for 0.0.0.0:8080 failed: port is already allocated
Penyebab
Container lain sudah memakai port tersebut.
Service lokal seperti Nginx, Apache, MySQL, PostgreSQL, atau Redis memakai port yang sama.
Docker Compose masih menjalankan container lama.
Port mapping di
docker-compose.yml
bentrok antar-service.
Aplikasi lokal dan container memakai port yang sama.
Solusi
Cek container berjalan:
docker ps
Cari proses yang memakai port:
sudo lsof -i :8080
Atau:
sudo netstat -tulpn | grep 8080
Hentikan container yang memakai port:
docker stop nama_container
Atau ubah port host:
docker run -p 8081:80 nginx
Di Docker Compose:
services: web: ports: – “8081:80”
Artinya port host
8081
diarahkan ke port container
80
.
Cara Mencegah
Buat standar port untuk setiap project.
Gunakan
.env
untuk port Compose.
Matikan container lama setelah selesai.
Jalankan
docker compose down
sebelum menjalankan konfigurasi baru jika perlu.
4. Build Failed
Build Failed terjadi ketika Docker gagal membuat image dari Dockerfile.
Penyebab
Build dapat gagal karena:
Syntax Dockerfile salah.
Base image tidak tersedia.
Package manager gagal install dependency.
File yang ingin di-copy tidak ada.
Network gagal saat download dependency.
Versi Node/PHP/Python/Go tidak cocok.
Build context terlalu besar.
Perintah di
RUN
mengembalikan exit code non-zero.
Solusi
Jalankan build dengan output lebih jelas:
docker build –progress=plain -t nama_image .
Jika memakai BuildKit dan ingin debugging lebih sederhana:
DOCKER_BUILDKIT=0 docker build -t nama_image .
Cek Dockerfile baris yang gagal. Misalnya:
COPY package.json package-lock.json ./ RUN npm ci
Pastikan file
package-lock.json
benar-benar ada. Jika tidak ada, gunakan:
COPY package.json ./ RUN npm install
Cek
.dockerignore
. Jangan sampai file penting ikut diabaikan:
node_modules .git .env
Jangan masukkan file yang dibutuhkan build ke
.dockerignore
.
Cara Mencegah
Buat Dockerfile bertahap dan mudah dibaca.
Pisahkan copy dependency dan source code agar cache build efektif.
Gunakan versi base image yang spesifik.
Jalankan build lokal sebelum deploy.
Simpan lock file dependency seperti
package-lock.json
,
composer.lock
,
poetry.lock
, atau
go.sum
.
5. Docker Daemon Error
Docker daemon adalah service utama yang menangani container, image, network, dan volume. Jika daemon bermasalah, perintah Docker tidak bisa berjalan.
Contoh error:
Cannot connect to the Docker daemon
Penyebab
Docker service belum berjalan.
User tidak punya permission ke Docker socket.
Docker Desktop belum dinyalakan.
Service Docker crash.
Disk penuh.
Konfigurasi daemon salah.
Socket Docker tidak tersedia.
Solusi
Di Linux, cek status Docker:
sudo systemctl status docker
Jalankan Docker:
sudo systemctl start docker
Aktifkan saat boot:
sudo systemctl enable docker
Jika perlu restart:
sudo systemctl restart docker
Cek apakah user punya akses:
docker ps
Jika perlu:
sudo usermod -aG docker $USER
Di Docker Desktop, pastikan aplikasi Docker Desktop berjalan dan tidak stuck.
Cara Mencegah
Monitor service Docker di server.
Jangan mengubah konfigurasi daemon tanpa backup.
Pastikan disk tidak penuh.
Gunakan versi Docker yang stabil.
6. Compose Error
Docker Compose membantu menjalankan banyak container sekaligus. Namun, error Compose sering muncul karena salah format YAML, nama service salah, environment variable tidak tersedia, atau perbedaan versi perintah.
Penyebab
Indentasi YAML salah.
File
docker-compose.yml
tidak valid.
Environment variable di
.env
tidak ada.
Service name salah.
Image tidak ditemukan.
Build context salah.
Volume atau network belum benar.
Menggunakan perintah lama
docker-compose
padahal environment memakai
docker compose
.
Solusi
Validasi konfigurasi Compose:
docker compose config
Jalankan:
docker compose up
Jalankan di background:
docker compose up -d
Build ulang:
docker compose up -d –build
Matikan semua service:
docker compose down
Jika perlu hapus volume:
docker compose down -v
Contoh Compose sederhana:
services: app: build: . ports: – “8080:80” environment: APP_ENV: production
Cara Mencegah
Gunakan indentasi 2 spasi.
Jalankan
docker compose config
sebelum deploy.
Simpan
.env.example
untuk mendokumentasikan variable.
Jangan mencampur konfigurasi development dan production tanpa file override yang jelas.
7. Volume Missing
Volume digunakan agar data tetap tersimpan walaupun container dihapus. Error volume bisa membuat data tidak muncul atau aplikasi gagal start.
Penyebab
Named volume belum dibuat.
Volume terhapus saat menjalankan
docker compose down -v
.
Nama volume berubah.
Mount path salah.
Aplikasi membaca folder berbeda dari yang dimount.
Data sebenarnya berada di volume lama.
Solusi
Lihat daftar volume:
docker volume ls
Inspect volume:
docker volume inspect nama_volume
Buat volume manual:
docker volume create nama_volume
Contoh Compose:
services: db: image: postgres:16 volumes: – pgdata:/var/lib/postgresql/data volumes: pgdata:
Jika data hilang setelah
down -v
, kemungkinan volume sudah terhapus. Karena itu, hati-hati memakai perintah tersebut di production.
Cara Mencegah
Gunakan named volume untuk database.
Jangan menjalankan
docker compose down -v
di production kecuali benar-benar paham risikonya.
Backup volume secara berkala.
Gunakan nama volume yang konsisten.
8. Bind Mount Error
Bind mount menghubungkan folder host ke folder container. Ini berguna untuk development, tetapi sering menyebabkan error path dan permission.
Penyebab
Path host tidak ada.
Path relatif salah.
Permission host tidak cocok.
File host menimpa file penting di container.
Perbedaan path Windows, macOS, dan Linux.
Folder kosong di host menimpa folder berisi dependency di container.
Contoh kasus Node.js:
volumes: – .:/app
Jika
/app/node_modules
di container tertimpa oleh folder host yang tidak punya
node_modules
, aplikasi bisa gagal.
Solusi
Pastikan path ada:
ls -la ./data
Gunakan path absolut jika perlu:
docker run -v /home/user/project/data:/app/data nama_image
Untuk Node.js, pisahkan
node_modules
:
services: app: volumes: – .:/app – /app/node_modules
Untuk database, lebih baik pakai named volume daripada bind mount biasa.
Cara Mencegah
Gunakan bind mount terutama untuk development.
Gunakan named volume untuk data penting.
Dokumentasikan path yang harus ada.
Hindari bind mount ke folder sistem penting dalam container.
9. Too Many Layers
Docker image terdiri dari layer. Error atau masalah “too many layers” bisa terjadi ketika image dibuat dengan terlalu banyak instruksi, terlalu banyak perubahan file, atau strategi build tidak efisien.
Penyebab
Terlalu banyak instruksi
RUN
,
COPY
, atau
ADD
.
Build menghasilkan image sangat besar.
Package manager cache tidak dibersihkan.
Multi-stage build tidak digunakan.
Menyalin seluruh project termasuk file tidak penting.
Base image terlalu besar.
Solusi
Gabungkan instruksi yang berkaitan:
RUN apt-get update && apt-get install -y \ curl \ unzip \ git \ && rm -rf /var/lib/apt/lists/*
Gunakan
.dockerignore
:
.git node_modules vendor storage/logs tmp .env
Gunakan image ringan jika sesuai:
FROM node:20-alpine
Gunakan multi-stage build untuk aplikasi frontend atau compiled language.
Cara Mencegah
Minimalkan jumlah layer yang tidak perlu.
Bersihkan cache package manager dalam layer yang sama.
Jangan copy file besar yang tidak dibutuhkan.
Gunakan multi-stage build untuk hasil akhir yang lebih kecil.
10. Disk Full
Docker dapat menghabiskan disk dengan cepat karena image lama, container berhenti, volume, build cache, dan log container.
Gejala
Build gagal tiba-tiba.
Container tidak bisa start.
Database container crash.
Docker daemon error.
Muncul pesan
no space left on device
.
Penyebab
Terlalu banyak image lama.
Container stopped menumpuk.
Volume tidak terpakai.
Build cache besar.
Log container sangat besar.
Database di volume membesar.
Solusi
Cek penggunaan disk Docker:
docker system df
Hapus container berhenti:
docker container prune
Hapus image tidak terpakai:
docker image prune
Hapus cache build:
docker builder prune
Hapus semua resource tidak terpakai:
docker system prune
Jika ingin termasuk volume tidak terpakai:
docker system prune –volumes
Gunakan perintah terakhir dengan hati-hati karena bisa menghapus data volume yang masih dibutuhkan.
Cara Mencegah
Jadwalkan cleanup aman secara berkala.
Batasi ukuran log container.
Monitor disk server.
Jangan menyimpan file upload besar di layer container.
Backup dan rotasi data penting.
11. Image Pull Failed
Error Image Pull Failed terjadi ketika Docker gagal mengunduh image dari registry seperti Docker Hub, GitHub Container Registry, atau registry private.
Penyebab
Nama image salah.
Tag image tidak tersedia.
Koneksi internet bermasalah.
Rate limit Docker Hub.
Registry private butuh login.
Sertifikat TLS bermasalah.
Arsitektur image tidak cocok.
Contoh:
pull access denied
Atau:
manifest not found
Solusi
Cek nama dan tag image:
docker pull nginx:latest
Jika memakai registry private:
docker login registry.example.com
Pastikan tag tersedia. Misalnya, jangan menulis:
image: node:99
Jika tag tersebut tidak ada.
Untuk platform berbeda, misalnya Apple Silicon:
docker run –platform linux/amd64 nama_image
Cara Mencegah
Gunakan tag image yang jelas, bukan asal
latest
.
Login ke registry private sebelum deploy.
Dokumentasikan registry dan tag.
Simpan image penting di registry yang stabil.
12. DNS Error
DNS error membuat container tidak bisa resolve domain seperti
google.com
,
api.example.com
, atau nama service internal.
Penyebab
DNS host bermasalah.
Konfigurasi Docker daemon DNS salah.
Network container rusak.
Service name di Compose salah.
Aplikasi memakai
localhost
padahal harus memakai nama service.
Firewall atau proxy membatasi akses.
Solusi
Tes dari dalam container:
docker exec -it nama_container sh
Lalu:
nslookup google.com
Atau:
ping google.com
Jika container tidak punya tool tersebut, gunakan image debugging:
docker run –rm busybox nslookup google.com
Atur DNS di Compose:
services: app: dns: – 8.8.8.8 – 1.1.1.1
Untuk komunikasi antar-service Compose, gunakan nama service:
DB_HOST=db
Bukan:
DB_HOST=localhost
Cara Mencegah
Gunakan service name untuk komunikasi antar-container.
Jangan hardcode IP container.
Pastikan DNS server host stabil.
Dokumentasikan konfigurasi proxy jika berada di jaringan kantor.
13. Network Bridge Error
Docker menggunakan network bridge default untuk menghubungkan container ke host dan internet. Network bridge error dapat menyebabkan container tidak saling terhubung atau tidak bisa keluar internet.
Penyebab
Network Docker rusak.
Konflik subnet dengan jaringan kantor/VPN.
Firewall memblokir bridge Docker.
iptables/nftables berubah.
Docker daemon belum restart setelah perubahan network.
Container berada di network berbeda.
Solusi
Lihat daftar network:
docker network ls
Inspect network:
docker network inspect bridge
Buat network baru:
docker network create app_network
Jalankan container pada network tersebut:
docker run –network app_network nama_image
Di Compose:
services: app: networks: – appnet db: networks: – appnet networks: appnet:
Jika konflik dengan VPN, atur subnet custom:
networks: appnet: ipam: config: – subnet: 172.28.0.0/16
Cara Mencegah
Gunakan network khusus per project.
Hindari memakai network default untuk semua container.
Waspadai konflik subnet dengan VPN.
Jangan hardcode IP container.
14. Healthcheck Failed
Healthcheck digunakan untuk menentukan apakah container benar-benar sehat, bukan hanya “running”.
Penyebab
Endpoint healthcheck salah.
Aplikasi belum siap saat healthcheck pertama berjalan.
Curl/wget tidak tersedia di image.
Timeout terlalu pendek.
Database dependency belum siap.
Aplikasi return status selain 2xx.
Contoh Dockerfile:
HEALTHCHECK CMD curl -f http://localhost:3000/health || exit 1
Solusi
Cek status:
docker ps
Inspect healthcheck:
docker inspect nama_container
Lihat log aplikasi:
docker logs nama_container
Pastikan endpoint health tersedia:
curl http://localhost:3000/health
Atur interval dan start period:
HEALTHCHECK \ CMD curl -f http://localhost:3000/health || exit 1
Cara Mencegah
Buat endpoint healthcheck yang ringan.
Jangan healthcheck ke endpoint berat.
Tambahkan
start_period
untuk aplikasi yang butuh waktu startup.
Pastikan tool healthcheck tersedia di image.
15. Restart Loop
Restart loop terjadi ketika container terus restart berulang-ulang. Biasanya statusnya terlihat seperti
Restarting
.
Penyebab
Aplikasi crash saat startup.
Restart policy selalu menghidupkan container gagal.
Environment variable salah.
Dependency seperti database belum siap.
Migration gagal.
Command utama exit.
File konfigurasi hilang.
Solusi
Cek container:
docker ps -a
Lihat log:
docker logs nama_container
Jika log terlalu cepat berulang, batasi output:
docker logs –tail=100 nama_container
Cek restart policy:
docker inspect nama_container
Jika perlu, jalankan tanpa restart policy untuk debugging:
docker run –rm -it –entrypoint sh nama_image
Di Compose, restart policy biasanya seperti:
restart: always
Untuk debugging, bisa sementara dihapus atau diganti:
restart: “no”
Cara Mencegah
Validasi konfigurasi sebelum container start.
Tambahkan retry koneksi database.
Jangan mengandalkan restart policy untuk menutupi bug.
Gunakan log startup yang jelas.
Jalankan migration dengan strategi yang aman, bukan selalu otomatis saat container start tanpa kontrol.
16. Multi-stage Build Error
Multi-stage build digunakan untuk menghasilkan image kecil dan bersih. Namun, error sering terjadi saat file dari stage sebelumnya tidak ditemukan.
Penyebab
Nama stage salah.
Path hasil build berbeda.
File tidak dibuat karena build gagal.
Dependency hanya ada di stage builder.
User permission berubah di final stage.
Binary tidak kompatibel dengan base image final.
Menyalin folder yang salah dari stage builder.
Contoh Error
COPY failed: stat /var/lib/docker/tmp/… no such file or directory
Solusi
Contoh multi-stage untuk Node.js frontend:
FROM node:20-alpine AS builder WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . RUN npm run build FROM nginx:alpine COPY /app/dist /usr/share/nginx/html
Pastikan hasil build memang berada di
/app/dist
. Untuk beberapa framework, output bisa berbeda:
Vite: biasanya
dist
Next.js:
.next
Nuxt:
.output
Angular:
dist/nama-project
Untuk Go:
FROM golang:1.22-alpine AS builder WORKDIR /app COPY . . RUN go build -o app . FROM alpine:latest WORKDIR /app COPY /app/app . CMD [“./app”]
Jika binary butuh library tertentu, final image
scratch
atau
alpine
mungkin tidak cukup.
Cara Mencegah
Beri nama stage dengan jelas, misalnya
AS builder
.
Cek output folder build sebelum menulis
COPY –from
.
Jangan asal menyalin path dari tutorial tanpa menyesuaikan framework.
Gunakan base image final yang kompatibel.
17. Container Tidak Bisa Mengakses Database
Walaupun tidak disebut langsung, error ini sangat sering muncul dalam project Docker Compose.
Penyebab
Aplikasi memakai
localhost
untuk database.
Database container belum siap.
Service name salah.
Port internal dan port host tertukar.
Network antar-service berbeda.
Credential database salah.
Solusi
Di Docker Compose, gunakan nama service database:
services: app: environment: DB_HOST: db DB_PORT: 5432 db: image: postgres:16
Jangan gunakan:
DB_HOST=localhost
Dari dalam container
app
,
localhost
berarti container
app
itu sendiri, bukan container database.
Cek koneksi:
docker compose exec app sh
Lalu tes ke host database sesuai tool yang tersedia.
Cara Mencegah
Gunakan service name Compose sebagai hostname.
Tambahkan retry connection di aplikasi.
Gunakan healthcheck untuk database.
Dokumentasikan environment variable database.
18. Container Bisa Jalan tetapi Tidak Bisa Diakses dari Browser
Kadang container terlihat running, tetapi aplikasi tidak bisa dibuka dari browser.
Penyebab
Port tidak dipublish ke host.
Aplikasi listen hanya ke
127.0.0.1
di dalam container.
Port container salah.
Firewall host memblokir port.
Reverse proxy salah konfigurasi.
Aplikasi crash setelah menerima request.
Solusi
Cek port:
docker ps
Pastikan ada mapping seperti:
0.0.0.0:8080->3000/tcp
Jika aplikasi Node.js, pastikan listen ke
0.0.0.0
:
app.listen(3000, ‘0.0.0.0’);
Jalankan:
docker run -p 8080:3000 nama_image
Lalu akses:
http://localhost:8080
Cara Mencegah
Bedakan port host dan port container.
Pastikan aplikasi listen ke semua interface.
Dokumentasikan port aplikasi.
Tes akses dari host setelah container start.
19. Docker Compose Environment Variable Tidak Terbaca
Compose bisa membaca variable dari file
.env
, tetapi sering terjadi salah paham antara
.env
untuk Compose dan
.env
untuk aplikasi.
Penyebab
File
.env
berada di folder yang salah.
Variable tidak didefinisikan.
Nama variable typo.
Aplikasi membutuhkan file
.env
di dalam container.
Compose variable substitution dianggap sama dengan environment aplikasi.
Solusi
Contoh:
services: app: image: myapp:${APP_TAG} environment: APP_ENV: ${APP_ENV}
File
.env
:
APP_TAG=1.0.0 APP_ENV=production
Cek hasil final Compose:
docker compose config
Jika aplikasi butuh file environment:
services: app: env_file: – .env
Cara Mencegah
Pisahkan
.env
Compose dan
.env
aplikasi jika perlu.
Gunakan
.env.example
.
Selalu validasi dengan
docker compose config
.
Jangan menyimpan secret di repository publik.
20. Dockerfile COPY Gagal
Error
COPY failed
sering terjadi saat Docker tidak menemukan file yang ingin disalin.
Penyebab
File tidak ada di build context.
Path salah.
.dockerignore
mengecualikan file.
Menjalankan build dari folder yang salah.
Huruf besar/kecil berbeda, terutama saat pindah dari Windows ke Linux.
Solusi
Jika Dockerfile:
COPY package.json .
Pastikan menjalankan build dari folder yang berisi
package.json
:
docker build -t app .
Jika Dockerfile berada di folder berbeda:
docker build -f docker/Dockerfile -t app .
Perhatikan bahwa titik terakhir adalah build context.
Cara Mencegah
Pahami konsep build context.
Jangan memasukkan file penting ke
.dockerignore
.
Gunakan path relatif dari root build context.
Jaga konsistensi nama file.
21. Docker Compose Service Name Salah
Service name dalam Compose berfungsi sebagai hostname internal antar-container.
Penyebab
Aplikasi memakai nama container yang berbeda dari nama service.
Service diganti nama tetapi environment belum diperbarui.
Menggunakan
container_name
lalu bingung dengan DNS Compose.
Network berbeda.
Solusi
Contoh benar:
services: api: environment: REDIS_HOST: redis redis: image: redis:7
Dari service
api
, host Redis adalah:
redis
Bukan
localhost
.
Cara Mencegah
Gunakan service name sederhana.
Hindari
container_name
jika tidak diperlukan.
Dokumentasikan host internal tiap service.
22. Docker Image Terlalu Besar
Image besar membuat build, pull, push, dan deployment menjadi lambat.
Penyebab
Base image terlalu besar.
Dependency development ikut masuk.
Cache package manager tidak dibersihkan.
File lokal seperti
.git
,
node_modules
, log, dan upload ikut tercopy.
Tidak memakai multi-stage build.
Solusi
Cek ukuran image:
docker images
Gunakan
.dockerignore
:
.git node_modules vendor .env logs coverage
Untuk Node.js production:
RUN npm ci –omit=dev
Gunakan multi-stage build.
Cara Mencegah
Pilih base image minimal.
Copy hanya file yang diperlukan.
Audit image secara berkala.
Jangan memasukkan secret atau file lokal tidak penting ke image.
23. Docker Log Terlalu Besar
Log container bisa memenuhi disk jika aplikasi menulis output terus-menerus.
Penyebab
Aplikasi terlalu banyak log.
Tidak ada log rotation.
Error berulang dalam restart loop.
Driver log default menyimpan file besar.
Solusi
Cek ukuran log container:
docker inspect nama_container
Atur log rotation di Compose:
services: app: logging: driver: json–file options: max-size: “10m” max-file: “3”
Cara Mencegah
Batasi log di production.
Gunakan log aggregation jika aplikasi besar.
Aktifkan log rotation.
Perbaiki error berulang, jangan hanya menghapus log.
24. Docker Cannot Remove Container
Kadang container tidak bisa dihapus karena masih berjalan, dipakai network, atau proses Docker bermasalah.
Penyebab
Container masih running.
Container sedang restart loop.
Resource masih dipakai.
Docker daemon bermasalah.
Ada dependency dari Compose.
Solusi
Stop container:
docker stop nama_container
Hapus:
docker rm nama_container
Paksa hapus:
docker rm -f nama_container
Untuk Compose:
docker compose down
Cara Mencegah
Gunakan Compose untuk lifecycle multi-container.
Hindari menjalankan container manual yang menabrak Compose.
Bersihkan container lama secara rutin.
25. Docker Network Tidak Bisa Dihapus
Network Docker tidak bisa dihapus jika masih digunakan container.
Penyebab
Masih ada container terhubung ke network.
Container stopped masih memakai network.
Compose project belum down.
Network default sedang digunakan.
Solusi
Cek network:
docker network inspect nama_network
Putuskan container dari network:
docker network disconnect nama_network nama_container
Atau matikan Compose:
docker compose down
Hapus network:
docker network rm nama_network
Cara Mencegah
Kelola network lewat Compose.
Hapus container lama sebelum menghapus network.
Gunakan nama project Compose yang jelas.
26. Docker Volume Tidak Bisa Dihapus
Volume tidak bisa dihapus jika masih digunakan container.
Penyebab
Container masih memakai volume.
Container stopped belum dihapus.
Volume termasuk data database aktif.
Compose masih memiliki service terkait.
Solusi
Cek volume:
docker volume inspect nama_volume
Lihat container terkait melalui inspect container jika perlu.
Hapus container dulu:
docker rm nama_container
Lalu hapus volume:
docker volume rm nama_volume
Untuk volume tidak terpakai:
docker volume prune
Cara Mencegah
Jangan hapus volume database tanpa backup.
Gunakan nama volume yang jelas.
Bedakan volume development dan production.
27. Docker Build Cache Membingungkan
Kadang perubahan kode tidak terlihat karena cache build masih dipakai.
Penyebab
Layer Docker masih cache.
Urutan instruksi Dockerfile tidak tepat.
File yang berubah tidak tercopy sebelum command dijalankan.
Compose tidak build ulang image.
Solusi
Build tanpa cache:
docker build –no-cache -t nama_image .
Dengan Compose:
docker compose build –no-cache docker compose up -d
Atau:
docker compose up -d –build
Cara Mencegah
Susun Dockerfile dengan benar.
Copy dependency file lebih dulu, lalu source code.
Gunakan cache untuk dependency, tetapi pastikan source code tetap diperbarui.
Pahami kapan harus build ulang image.
28. Docker Container Keluar dengan Exit Code 137
Exit code 137 biasanya menandakan container dihentikan karena kehabisan memory atau dibunuh oleh sistem.
Penyebab
Aplikasi memakai RAM terlalu besar.
Server kehabisan memory.
Limit memory container terlalu kecil.
Proses build terlalu berat.
Query atau job aplikasi tidak efisien.
Solusi
Cek resource:
Cek log kernel di Linux:
dmesg | grep -i killed
Naikkan limit memory jika memang perlu:
docker run –memory=1g nama_image
Optimalkan aplikasi agar tidak memuat data besar sekaligus.
Cara Mencegah
Monitor memory container.
Gunakan limit resource yang realistis.
Pecah job besar menjadi chunk.
Hindari proses berat di container kecil.
29. Docker Container Keluar dengan Exit Code 1
Exit code 1 adalah error umum yang berarti proses utama gagal.
Penyebab
Command salah.
Konfigurasi aplikasi salah.
Dependency tidak tersedia.
File tidak ditemukan.
Exception saat startup.
Environment variable tidak lengkap.
Solusi
Cek log:
docker logs nama_container
Jalankan image secara interaktif:
docker run –rm -it –entrypoint sh nama_image
Coba jalankan command manual dari dalam container.
Cara Mencegah
Validasi konfigurasi saat startup.
Buat pesan error yang jelas.
Gunakan entrypoint script yang aman.
Tes image sebelum deploy.
30. Docker Compose Depends On Tidak Menunggu Database Ready
Banyak developer mengira
depends_on
menunggu database siap menerima koneksi. Padahal, dalam banyak kasus,
depends_on
hanya memastikan container dependency dibuat lebih dulu.
Penyebab
Database container sudah running tetapi belum ready.
Aplikasi langsung konek dan gagal.
Tidak ada retry connection.
Healthcheck belum dipakai.
Solusi
Tambahkan healthcheck database:
services: db: image: postgres:16 healthcheck: test: [“CMD-SHELL”, “pg_isready -U postgres”] interval: 5s timeout: 5s retries: 5
Tambahkan retry connection di aplikasi.
Untuk beberapa versi Compose, bisa memakai kondisi healthcheck:
depends_on: db: condition: service_healthy
Cara Mencegah
Jangan bergantung hanya pada urutan start container.
Gunakan retry di aplikasi.
Tambahkan healthcheck untuk service penting.
Pisahkan migration dari startup aplikasi jika perlu.
31. Docker Compose Orphan Containers
Orphan containers muncul ketika service di Compose file sudah dihapus atau diganti nama, tetapi container lama masih ada.
Gejala
Muncul pesan seperti:
Found orphan containers
Penyebab
Nama service berubah.
File Compose berubah.
Project name berubah.
Container lama belum dihapus.
Solusi
Jalankan:
docker compose up -d –remove-orphans
Atau:
docker compose down –remove-orphans
Cara Mencegah
Hapus service lama setelah rename.
Gunakan project name yang konsisten.
Bersihkan environment development secara berkala.
32. Docker Desktop WSL Error
Pada Windows, Docker Desktop sering berkaitan dengan WSL2.
Penyebab
WSL2 tidak aktif.
Docker Desktop belum terkoneksi ke distro WSL.
Resource WSL habis.
Distro Linux bermasalah.
Virtualization belum aktif di BIOS.
Solusi
Cek WSL:
wsl –l –v
Restart WSL:
wsl —shutdown
Lalu buka Docker Desktop kembali.
Pastikan integration aktif di Docker Desktop untuk distro yang digunakan.
Cara Mencegah
Gunakan WSL2, bukan WSL1.
Update Docker Desktop secara berkala.
Batasi resource sesuai kemampuan laptop.
Simpan project di filesystem Linux WSL untuk performa lebih baik.
33. Docker Build Lambat
Build lambat mengganggu workflow development dan CI/CD.
Penyebab
Build context terlalu besar.
Tidak memakai cache dependency.
.dockerignore
tidak ada.
Menginstall ulang dependency setiap build.
Base image besar.
Internet lambat saat download package.
Solusi
Tambahkan
.dockerignore
:
.git node_modules vendor dist build coverage .env
Susun Dockerfile agar dependency cache efektif:
COPY package*.json ./ RUN npm ci COPY . .
Dengan begitu,
npm ci
hanya diulang jika
package.json
atau lock file berubah.
Cara Mencegah
Optimalkan Dockerfile.
Gunakan cache CI/CD.
Gunakan registry mirror jika perlu.
Hindari copy file tidak penting.
34. Docker Compose File Tidak Ditemukan
Error ini terjadi ketika perintah Compose dijalankan dari folder yang salah atau nama file berbeda.
Penyebab
Tidak ada
docker-compose.yml
atau
compose.yml
.
Perintah dijalankan dari direktori salah.
File memakai nama custom.
Path file salah.
Solusi
Jalankan dari folder yang berisi file Compose:
docker compose up -d
Jika file berbeda:
docker compose -f docker-compose.prod.yml up -d
Gabungkan beberapa file:
docker compose -f docker-compose.yml -f docker-compose.override.yml up -d
Cara Mencegah
Letakkan file Compose di root project.
Dokumentasikan perintah start project.
Gunakan nama file standar jika memungkinkan.
35. Docker Secret Bocor ke Image
Ini bukan error runtime biasa, tetapi sangat berbahaya. Secret seperti token, password,
.env
, atau private key bisa tidak sengaja masuk ke image.
Penyebab
COPY . .
menyalin semua file.
.dockerignore
tidak mengecualikan
.env
.
Secret ditulis dalam Dockerfile dengan
ENV
.
Token digunakan dalam
RUN
lalu tersimpan di layer.
Image dipush ke registry publik.
Solusi
Tambahkan
.dockerignore
:
.env *.pem *.key id_rsa id_rsa.pub
Jangan tulis secret langsung:
ENV API_KEY=secret
Gunakan environment runtime:
docker run -e API_KEY=xxxx nama_image
Atau gunakan secret management pada platform deployment.
Cara Mencegah
Audit image sebelum push.
Jangan copy seluruh folder tanpa
.dockerignore
.
Gunakan build secret jika perlu.
Rotasi secret jika sudah terlanjur bocor.
36. Docker Entrypoint Error
Entrypoint error membuat container gagal start karena script awal bermasalah.
Penyebab
File entrypoint tidak executable.
Shebang salah.
Format line ending Windows CRLF.
Path script salah.
Script exit karena command gagal.
Dependency shell tidak tersedia.
Solusi
Pastikan executable:
chmod +x docker-entrypoint.sh
Gunakan shebang:
#!/bin/sh
Jika file dibuat di Windows, ubah line ending ke LF.
Dockerfile:
COPY docker-entrypoint.sh /usr/local/bin/ ENTRYPOINT [“docker-entrypoint.sh”]
Cara Mencegah
Simpan script entrypoint dengan format LF.
Gunakan
set -e
secara hati-hati.
Tes entrypoint secara lokal.
Jangan membuat entrypoint terlalu kompleks.
37. Docker Timezone Salah
Timezone salah bisa membuat log, scheduler, cron, dan timestamp aplikasi membingungkan.
Penyebab
Container memakai UTC.
Timezone aplikasi berbeda dari timezone server.
Environment
TZ
tidak diset.
Image minimal tidak punya data timezone.
Solusi
Set environment:
services: app: environment: TZ: Asia/Jakarta
Untuk Debian/Ubuntu image, install timezone data jika perlu:
RUN apt-get update && apt-get install -y tzdata
Cara Mencegah
Gunakan UTC untuk sistem internal jika memungkinkan.
Tampilkan timezone lokal di UI.
Dokumentasikan timezone aplikasi.
Set
TZ
jika aplikasi benar-benar membutuhkan local time.
38. Docker Cron Tidak Jalan
Beberapa aplikasi menjalankan cron di dalam container. Ini sering bermasalah jika tidak dikonfigurasi dengan benar.
Penyebab
Cron service tidak berjalan.
Container hanya menjalankan satu proses utama.
File crontab salah permission.
Timezone salah.
Log cron tidak terlihat.
Command cron membutuhkan environment variable yang tidak tersedia.
Solusi
Lebih baik jalankan scheduler sebagai service terpisah di Compose.
Contoh:
services: scheduler: build: . command: php artisan schedule:work
Untuk aplikasi Node/Python, gunakan worker terpisah sesuai kebutuhan.
Cara Mencegah
Hindari menjalankan terlalu banyak proses dalam satu container.
Pisahkan web, worker, dan scheduler.
Pastikan log scheduler masuk stdout/stderr.
Gunakan orchestrator jika aplikasi production kompleks.
39. Docker Database Data Hilang Setelah Recreate
Data database hilang setelah container dibuat ulang biasanya disebabkan volume tidak dipakai dengan benar.
Penyebab
Data disimpan di filesystem container, bukan volume.
Menggunakan
docker compose down -v
.
Nama volume berubah.
Bind mount diarahkan ke folder kosong yang salah.
Database image memakai path data berbeda.
Solusi
Gunakan named volume:
services: mysql: image: mysql:8 volumes: – mysql_data:/var/lib/mysql volumes: mysql_data:
Backup sebelum recreate:
docker exec nama_mysql mysqldump -u root -p database > backup.sql
Cara Mencegah
Selalu gunakan volume untuk database.
Jangan hapus volume tanpa backup.
Dokumentasikan path data resmi dari image database.
Uji proses backup dan restore.
40. Docker Compose Build Menggunakan Image Lama
Kadang Compose tetap memakai image lama meskipun kode sudah berubah.
Penyebab
Tidak menjalankan build ulang.
Image tag sama.
Cache build masih dipakai.
Service memakai
image
tanpa
build
.
Container lama belum direcreate.
Solusi
Build ulang:
docker compose up -d –build
Jika masih bermasalah:
docker compose build –no-cache docker compose up -d –force-recreate
Cek image yang dipakai:
docker compose images
Cara Mencegah
Gunakan tag image yang jelas di deployment.
Build image di CI/CD.
Paksa recreate saat deploy jika diperlukan.
Jangan mengandalkan
latest
untuk production.
Checklist Cepat Troubleshooting Docker
Jika belum tahu error berasal dari mana, gunakan urutan berikut.
1. Cek Container
docker ps -a
Perhatikan status container:
Up
,
Exited
,
Restarting
, atau
Created
.
2. Cek Log
docker logs nama_container
Untuk Compose:
docker compose logs nama_service
3. Cek Konfigurasi Compose
docker compose config
4. Cek Port
docker ps sudo lsof -i :PORT
5. Cek Disk
docker system df df -h
6. Cek Network
docker network ls docker network inspect nama_network
7. Cek Volume
docker volume ls docker volume inspect nama_volume
8. Cek Resource
docker stats
9. Build Ulang Jika Perlu
docker compose up -d –build
Atau tanpa cache:
docker compose build –no-cache
10. Bersihkan Resource Tidak Terpakai
docker system prune
Gunakan
–volumes
hanya jika yakin volume tidak berisi data penting.
Contoh Docker Compose yang Lebih Aman untuk Development
Berikut contoh sederhana aplikasi web dengan database dan Redis:
services: app: build: . ports: – “8080:3000” environment: NODE_ENV: development DB_HOST: db REDIS_HOST: redis volumes: – .:/app – /app/node_modules depends_on: – db – redis networks: – appnet db: image: postgres:16 environment: POSTGRES_DB: app POSTGRES_USER: app POSTGRES_PASSWORD: secret volumes: – pgdata:/var/lib/postgresql/data networks: – appnet redis: image: redis:7 networks: – appnet volumes: pgdata: networks: appnet:
Beberapa poin penting dari contoh di atas:
DB_HOST
memakai nama service
db
, bukan
localhost
.
Database memakai named volume
pgdata
.
Aplikasi dan database berada dalam network yang sama.
Port host
8080
diarahkan ke port container
3000
.
node_modules
dipisahkan agar bind mount tidak menimpa dependency container.
Contoh Dockerfile yang Lebih Rapi untuk Node.js
FROM node:20-alpine WORKDIR /app COPY package*.json ./ RUN npm ci COPY . . EXPOSE 3000 CMD [“npm”, “start”]
Tambahkan
.dockerignore
:
.git node_modules npm-debug.log .env coverage dist
Untuk production, bisa dibuat multi-stage:
FROM node:20-alpine AS deps WORKDIR /app COPY package*.json ./ RUN npm ci –omit=dev FROM node:20-alpine AS runner WORKDIR /app ENV NODE_ENV=production COPY /app/node_modules ./node_modules COPY . . EXPOSE 3000 CMD [“npm”, “start”]
Praktik Terbaik agar Docker Lebih Stabil
1. Gunakan
.dockerignore
Tanpa
.dockerignore
, Docker bisa mengirim terlalu banyak file ke build context. Ini membuat build lambat dan berisiko memasukkan file sensitif ke image.
2. Jangan Gunakan
latest
untuk Production
Tag
latest
bisa berubah tanpa disadari. Gunakan tag spesifik seperti:
postgres:16.3 redis:7.2 node:20-alpine
3. Pisahkan Service Berdasarkan Tugas
Jangan paksa satu container menjalankan web server, worker, scheduler, dan database sekaligus. Lebih baik pisahkan:
app
worker
scheduler
db
redis
4. Gunakan Named Volume untuk Data Penting
Database sebaiknya memakai named volume. Bind mount lebih cocok untuk development source code.
5. Jangan Simpan Secret di Image
Secret harus diberikan saat runtime melalui environment variable, secret manager, atau konfigurasi platform deployment.
6. Monitor Disk dan Log
Docker bisa memenuhi disk secara diam-diam. Jalankan pengecekan rutin:
docker system df
7. Gunakan Healthcheck
Healthcheck membantu membedakan container yang sekadar hidup dengan container yang benar-benar siap melayani request.
8. Dokumentasikan Perintah Penting
Setiap project sebaiknya punya dokumentasi seperti:
docker compose up -d docker compose logs -f docker compose down docker compose exec app sh
9. Gunakan CI/CD untuk Build Image
Build image di server manual sering menimbulkan perbedaan environment. CI/CD membuat proses lebih konsisten.
10. Backup Volume Production
Volume Docker bukan pengganti backup. Untuk database, tetap gunakan mekanisme backup resmi seperti
pg_dump
,
mysqldump
, snapshot volume, atau backup managed database.
Kesimpulan
Docker sangat powerful untuk membuat environment aplikasi yang konsisten, tetapi error tetap sering terjadi jika konfigurasi container, image, volume, network, port, permission, atau Compose tidak dipahami dengan benar. Error seperti Container Exited, Permission Denied, Port Already Allocated, Build Failed, Docker Daemon Error, Compose Error, Volume Missing, Bind Mount Error, Too Many Layers, Disk Full, Image Pull Failed, DNS Error, Network Bridge Error, Healthcheck Failed, Restart Loop, dan Multi-stage Build Error adalah masalah yang sangat umum dalam penggunaan Docker sehari-hari.
Cara terbaik menyelesaikan error Docker adalah mulai dari hal dasar: cek status container dengan
docker ps -a
, baca log dengan
docker logs
, validasi Compose dengan
docker compose config
, cek port, cek volume, cek network, dan pastikan Docker daemon berjalan normal. Untuk build error, baca output build secara teliti, periksa Dockerfile,
.dockerignore
, build context, dependency, dan cache.
Di sisi pencegahan, gunakan Dockerfile yang rapi, image tag yang jelas, named volume untuk data penting, network khusus per project, healthcheck untuk service penting, log rotation, serta deployment workflow yang konsisten. Dengan memahami pola error dan cara troubleshooting di atas, developer bisa mengurangi waktu debugging, menjaga aplikasi tetap stabil, dan menggunakan Docker dengan lebih percaya diri baik di lokal, staging, maupun production.
