Cách sửa lỗi Docker: 'executable file not found in $PATH'

Vấn đề

Tất cả chúng ta đều đã từng gặp tình huống này: bạn chạy lệnh docker run, mong đợi ứng dụng khởi động, nhưng nó bị lỗi ngay lập tức. Thay vì nhật ký ứng dụng, bạn lại nhận được một loạt văn bản từ OCI (Open Container Initiative) runtime. Điều này xảy ra do Docker đang cố gắng kích hoạt một lệnh đơn giản là không tồn tại trong đường dẫn tìm kiếm của container.

Lỗi thường trông như thế này:

OCI runtime create failed: container_linux.go:349: starting container process caused "exec: \"python\": executable file not found in $PATH": unknown

Mặc dù ví dụ cụ thể này gắn cờ "python", bạn cũng sẽ thấy hành vi tương tự với node, npm, sh, hoặc thậm chí là một shell script tùy chỉnh mà bạn vừa thêm vào image của mình.

Tóm tắt: Cách khắc phục nhanh

Kiểm tra tên binary: Các image hiện đại như Ubuntu 22.04 hoặc Debian Bullseye sử dụng python3. Lệnh python thường không được ánh xạ.
Sử dụng đường dẫn tuyệt đối: Đừng đoán mò nữa. Hãy đổi CMD ["python", "app.py"] thành CMD ["/usr/bin/python3", "app.py"].
Kiểm tra base image của bạn: Các image tối giản như alpine (chỉ khoảng ~5MB) thiếu hầu hết mọi thứ. Bạn phải cài đặt các công cụ của mình một cách thủ công.
Thiết lập PATH: Nếu bạn sử dụng các thư mục tùy chỉnh, hãy sử dụng ENV PATH="/your/path:${PATH}" bên trong Dockerfile.

Các nguyên nhân gốc rễ phổ biến

1. Xung đột đặt tên giữa Python 2 và Python 3

Đây là nguyên nhân lớn nhất. Các bản phân phối Linux cũ hơn đã liên kết lệnh python với phiên bản 2.7. Kể từ khi Python 2 kết thúc vòng đời, các base image hiện đại đã loại bỏ nó hoàn toàn. Nếu bạn sử dụng python:3.11-slim, binary thường được đặt tên là python. Tuy nhiên, nếu bạn bắt đầu với một image ubuntu:latest thô và chạy apt install python3, hệ thống chỉ nhận diện python3. Docker sẽ không tự động tạo alias này cho bạn.

2. Bẫy "Image tối giản"

Alpine Linux là một lựa chọn yêu thích cho môi trường production vì dung lượng nhỏ gọn. Nhưng có một vấn đề. Nó sử dụng musl libc và busybox thay vì các công cụ gnu. Nếu script của bạn bắt đầu bằng #!/bin/bash, một container Alpine sẽ báo lỗi "not found" vì theo mặc định nó chỉ có /bin/sh. Bạn đang cố gắng sử dụng một công cụ không có sẵn trong hệ thống.

3. Docker không tải Profile của bạn

Khi bạn đăng nhập vào một máy chủ Linux, nó sẽ tải .bashrc hoặc .profile. Docker không làm điều này. Khi chạy một CMD, nó sử dụng một môi trường rất cơ bản. Nếu bạn đã cài đặt một binary vào /opt/my-app/bin, Docker sẽ không tìm kiếm ở đó trừ khi bạn đã cập nhật biến PATH một cách rõ ràng trong Dockerfile.

Các bước khắc phục từng bước

Cách A: Cập nhật cú pháp lệnh

Nếu logs thông báo lỗi về python, hãy thử chuyển sang python3. Đây là cách khắc phục nhanh nhất cho các image dựa trên Debian.

# Cũ và bị lỗi:
CMD ["python", "main.py"]

# Mới và hoạt động:
CMD ["python3", "main.py"]

Cách B: Sử dụng đường dẫn tuyệt đối

Loại bỏ việc đoán mò bằng cách cho Docker biết chính xác vị trí của tệp. Không chắc nó ở đâu? Hãy chạy một container tạm thời để tìm hiểu:

docker run --rm python:3.9-slim which python

Khi bạn đã có đường dẫn đó (ví dụ: /usr/local/bin/python), hãy cập nhật Dockerfile của bạn:

ENTRYPOINT ["/usr/local/bin/python", "app.py"]

Cách C: Cài đặt các gói còn thiếu (Cách khắc phục cho Alpine)

Nếu bạn đang sử dụng Alpine và cần Python, bạn phải thêm nó trong quá trình build. Sử dụng trình quản lý gói apk. Chúng ta cũng có thể tạo một symlink để lệnh python hoạt động như mong đợi.

FROM alpine:3.19

# Cài đặt python3 và tạo một symlink
RUN apk add --no-cache python3 && ln -sf python3 /usr/bin/python

WORKDIR /app
COPY . .

CMD ["python", "app.py"]

Cách D: Thiết lập PATH thủ công

Đối với các binary tùy chỉnh, hãy thêm vị trí của chúng vào môi trường một cách rõ ràng. Điều này đảm bảo Docker sẽ tìm kiếm trong các thư mục tùy chỉnh của bạn trước khi bỏ cuộc.

FROM node:20-slim

WORKDIR /app
COPY . .

# Đảm bảo các script tùy chỉnh của chúng ta có thể tìm thấy được
ENV PATH="/app/scripts:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"

CMD ["run-custom-task"]

Cách xác minh bản sửa lỗi

Đừng lãng phí thời gian build lại toàn bộ pipeline CI/CD của bạn. Hãy debug image một cách tương tác để xem điều gì thực sự đang diễn ra bên trong hệ thống tệp:

docker run --rm -it --entrypoint /bin/sh your-image-name

Khi bạn đã ở bên trong, hãy chạy ba lệnh sau:

echo $PATH: Nó có bao gồm thư mục chứa ứng dụng của bạn không?
which python3: Hệ điều hành có thực sự nhìn thấy binary không?
ls -l /usr/bin/python*: Xem chính xác những phiên bản nào đã được cài đặt.

Danh sách kiểm tra tóm tắt

Gói phần mềm đã thực sự được cài đặt trong Dockerfile của bạn chưa?
Bạn đã kiểm tra kỹ các lỗi chính tả trong CMD hoặc ENTRYPOINT chưa?
Bạn có đang gọi python trong khi image chỉ có python3 không?
Shebang của script (ví dụ: #!/bin/bash) có khớp với shell tồn tại trong image không?
Bạn có đang sử dụng "exec form" (ngoặc vuông JSON) không? Hãy nhớ rằng, ["cmd"] không sử dụng shell, vì vậy nó sẽ không giải quyết các alias hoặc biến giống như một chuỗi thô.