Dockerfile not found: Penyebab, Cara Validasi, dan Solusi Teknis Paling Akurat

Error Dockerfile not found muncul ketika Docker gagal menemukan file Dockerfile saat menjalankan proses build image. Error ini biasanya terjadi ketika perintah docker build atau proses build di Docker Compose dan pipeline CI/CD dijalankan dari konteks direktori yang salah atau ketika nama dan lokasi Dockerfile tidak sesuai dengan ekspektasi Docker. Dalam praktik lapangan, error ini termasuk salah satu kegagalan build paling sering ditemui, baik oleh developer pemula maupun engineer berpengalaman.

Secara teknis, Docker mengandalkan Dockerfile sebagai instruksi utama untuk membangun image. Ketika file ini tidak ditemukan, proses build akan berhenti sebelum tahap parsing instruksi dimulai. Tidak ada layer yang dibuat, tidak ada base image yang ditarik, dan Docker daemon langsung mengembalikan error. Kondisi ini sering terjadi pada environment multi-repo, monorepo, atau saat struktur direktori proyek berubah tanpa penyesuaian perintah build.

Error Dockerfile not found juga umum muncul pada sistem yang menggunakan automated build seperti GitHub Actions, GitLab CI, atau Jenkins. Pada konteks ini, error dipicu oleh path yang tidak konsisten, working directory yang salah, atau konfigurasi pipeline yang mengasumsikan lokasi Dockerfile tertentu.

Penjelasan Error Dockerfile Not Found

Error Dockerfile not found berarti Docker tidak dapat menemukan file bernama Dockerfile di build context yang ditentukan. Secara default, Docker mencari file dengan nama persis Dockerfile (case-sensitive pada sistem Linux) di root direktori build context. Jika file tidak ada, tidak dapat diakses, atau berada di lokasi berbeda tanpa flag eksplisit, Docker akan menghentikan proses.

Error ini muncul pada tahap awal proses build, tepat setelah Docker daemon menerima perintah build dan sebelum instruksi FROM dieksekusi. Tidak ada proses container runtime yang berjalan karena error terjadi murni pada tahap build image. Pada log, error biasanya muncul sebagai:

unable to prepare context: unable to evaluate symlinks in Dockerfile path: lstat Dockerfile: no such file or directory

Lingkungan yang paling sering terdampak adalah Linux dan macOS karena sistem file yang case-sensitive. Pada Windows, error serupa bisa muncul akibat perbedaan path separator atau working directory PowerShell versus CMD. Versi Docker Engine tidak terlalu berpengaruh, tetapi Docker Desktop dan Docker CLI yang dijalankan melalui wrapper CI sering memperbesar potensi error ini.

Penyebab Utama Dockerfile Not Found

Dockerfile Tidak Berada di Build Context

Docker hanya dapat mengakses file yang berada di dalam build context. Jika Dockerfile berada di luar direktori yang dijadikan context pada perintah docker build, Docker tidak akan menemukannya. Kondisi ini sering terjadi ketika developer menjalankan perintah build dari direktori yang lebih tinggi atau lebih rendah dari lokasi Dockerfile.

Contoh kondisi nyata adalah struktur proyek seperti:

project-root/
├── docker/
│   └── Dockerfile
└── app/

Menjalankan docker build . dari project-root tanpa flag tambahan akan menyebabkan error karena Dockerfile berada di subdirektori docker.

Nama File Dockerfile Tidak Sesuai

Docker secara default hanya mencari file bernama Dockerfile tanpa ekstensi tambahan. File dengan nama seperti dockerfile, Dockerfile.dev, atau Dockerfile.prod tidak akan dikenali kecuali ditentukan secara eksplisit menggunakan flag -f. Pada sistem Linux, perbedaan huruf besar dan kecil juga menjadi penyebab umum.

Di lapangan, error ini sering muncul setelah refactor environment atau saat mengadopsi multi-stage build dengan beberapa Dockerfile khusus environment.

Working Directory Salah Saat Menjalankan Build

Pada environment CI/CD, working directory sering kali berbeda dari yang diasumsikan developer. Pipeline bisa mengeksekusi perintah build dari direktori root repository atau dari subdirektori tertentu. Jika perintah build tidak menyesuaikan path Dockerfile dan context, error akan muncul meskipun file sebenarnya ada.

Masalah ini juga sering terjadi saat menggunakan Docker Compose yang dipanggil dari direktori berbeda dengan file docker-compose.yml.

File Dockerfile Tidak Termasuk dalam Repository

Dalam beberapa kasus, Dockerfile ada di local development tetapi tidak ikut ter-commit ke repository. Akibatnya, pipeline CI/CD tidak menemukan file tersebut. Ini sering terjadi karena .gitignore yang salah konfigurasi atau asumsi bahwa Dockerfile tidak perlu disertakan.

Permission atau Symlink Bermasalah

Docker memerlukan akses read ke Dockerfile. Jika permission file terlalu restriktif atau Dockerfile berupa symbolic link yang mengarah ke path di luar build context, Docker akan gagal membacanya. Pada Linux server dengan konfigurasi keamanan ketat, kasus ini cukup sering terjadi.

Cara Memverifikasi Penyebab Error Dockerfile Not Found

Langkah pertama adalah memastikan lokasi Dockerfile dengan menjalankan perintah:

ls -la

Tujuannya untuk memverifikasi apakah file Dockerfile benar-benar ada di direktori saat ini dan memiliki permission read. Pastikan nama file sesuai dan tidak memiliki ekstensi tersembunyi.

Selanjutnya, verifikasi build context dengan menjalankan:

pwd

Perintah ini memastikan direktori aktif saat perintah docker build dijalankan. Bandingkan path ini dengan lokasi Dockerfile.

Jika menggunakan flag -f, pastikan path Dockerfile valid:

docker build -f docker/Dockerfile .

Tujuannya untuk memastikan Docker diarahkan ke file yang benar. Jika error tetap muncul, periksa apakah path tersebut berada di dalam build context.

Pada Docker Compose, periksa konfigurasi di docker-compose.yml, khususnya bagian:

build:
  context: .
  dockerfile: Dockerfile

Pastikan nilai context dan dockerfile sesuai dengan struktur direktori aktual.

Untuk pipeline CI/CD, periksa log step build dan pastikan working directory diset dengan benar, misalnya menggunakan working-directory pada GitHub Actions atau before_script pada GitLab CI.

Solusi Utama Dockerfile Not Found

Solusi utama adalah menyelaraskan lokasi Dockerfile, build context, dan perintah build. Jika Dockerfile berada di direktori yang sama dengan context, jalankan:

docker build -t nama-image .

Jika Dockerfile berada di subdirektori, gunakan flag -f dan tentukan context dengan benar:

docker build -f docker/Dockerfile .

Pendekatan ini bekerja karena Docker diberi instruksi eksplisit mengenai lokasi Dockerfile, sementara context tetap mencakup semua file yang dibutuhkan selama build.

Jika menggunakan Docker Compose, pastikan konfigurasi build eksplisit:

build:
  context: .
  dockerfile: docker/Dockerfile

Solusi ini memastikan Docker Compose tidak bergantung pada asumsi default lokasi Dockerfile.

Pada CI/CD, tambahkan perintah untuk berpindah ke direktori yang benar sebelum build:

cd app
docker build .

Langkah ini menyelaraskan working directory dengan lokasi Dockerfile.

Solusi Alternatif Berdasarkan Lingkungan

Pada Windows, pastikan perintah dijalankan dari shell yang konsisten dan path menggunakan format yang sesuai. Hindari mencampur PowerShell dan WSL tanpa penyesuaian path.

Pada server production dengan permission ketat, pastikan Docker daemon memiliki akses read ke direktori proyek dan Dockerfile tidak berada di path yang dibatasi oleh SELinux atau AppArmor.

Pada pipeline CI/CD, solusi alternatif adalah menyalin Dockerfile ke root context sebelum build menggunakan langkah script. Pendekatan ini sering digunakan pada monorepo untuk menyederhanakan pipeline.

Kesalahan yang Sering Dilakukan Saat Memperbaiki Error

Kesalahan paling umum adalah menyalin Dockerfile ke direktori sembarang tanpa memahami konsep build context. Pendekatan ini sering memicu error lanjutan seperti file tidak ditemukan saat COPY.

Kesalahan lain adalah mengganti nama Dockerfile tanpa menyesuaikan perintah build atau konfigurasi Compose. Secara teknis, Docker tidak melakukan auto-discovery terhadap variasi nama file.

Banyak pengguna juga mencoba menjalankan build dengan sudo atau mengubah permission secara berlebihan. Ini tidak menyelesaikan masalah jika akar penyebabnya adalah path dan context yang salah.

Pencegahan Error Dockerfile Not Found di Masa Depan

Praktik terbaik adalah menempatkan Dockerfile di root build context atau mendokumentasikan dengan jelas lokasi dan nama Dockerfile. Gunakan struktur direktori yang konsisten di seluruh environment.

Selalu gunakan flag -f secara eksplisit jika Dockerfile tidak berada di root. Pada Docker Compose, definisikan context dan dockerfile secara eksplisit untuk menghindari asumsi default.

Pastikan Dockerfile selalu disertakan dalam version control dan tidak diabaikan oleh .gitignore. Untuk CI/CD, set working directory secara eksplisit dan hindari dependensi terhadap default runner behavior.

Penutup

Error Dockerfile not found bukanlah masalah pada Docker Engine, melainkan indikasi ketidaksinkronan antara lokasi file, build context, dan cara perintah build dijalankan. Dengan memahami bagaimana Docker mencari dan memproses Dockerfile, error ini dapat diidentifikasi dan diselesaikan secara deterministik. Pendekatan yang disiplin terhadap struktur direktori, konfigurasi build, dan pipeline akan menghilangkan error ini secara permanen dan membuat proses containerization lebih stabil di semua environment.

Berbagi :