Cách khắc phục lỗi “Docker: Invalid Reference Format”

Docker giúp việc build, chạy và quản lý container trở nên dễ dàng. Tuy nhiên, bạn có thể gặp lỗi "Invalid Reference Format" khi chạy hoặc build image. Trong hầu hết các trường hợp, sự cố này là do một lỗi định dạng nhỏ trong tên hoặc tag image. Ví dụ, lỗi có thể do chữ in hoa, ký tự đặc biệt hoặc thiếu giá trị. Hướng dẫn này sẽ giải thích các nguyên nhân phổ biến gây ra lỗi này và cách khắc phục để ngăn ngừa sự cố tái diễn.

Sửa lỗi "Invalid Reference Format"

Hãy cùng tìm hiểu những nguyên nhân phổ biến nhất gây ra lỗi "Invalid Reference Format" và cách khắc phục:

Chữ in hoa trong tên image

Docker yêu cầu tên image phải được viết thường. Ngay cả một chữ in hoa cũng có thể khiến định dạng bị lỗi. Ví dụ, chạy lệnh sau sẽ gây ra lỗi:

docker pull NGINX

Để tránh lỗi này, hãy luôn kiểm tra kỹ xem tên image của bạn có được viết thường hay không trước khi chạy lệnh.

docker pull nginx

Ký tự đặc biệt hoặc không hợp lệ

Đôi khi người dùng vô tình thêm các ký tự mà Docker không cho phép. Các ký tự này bao gồm dấu @, khoảng trắng hoặc các ký tự được sao chép từ trang web hoặc tài liệu trông bình thường nhưng thực tế không phải vậy.

Ví dụ, lệnh sau chứa ký tự đặc biệt @, sẽ gây ra lỗi sau:

docker run ubuntu@:latest

Để khắc phục lỗi này, hãy đảm bảo rằng không có ký tự thừa hoặc vấn đề định dạng nào trong lệnh. Bạn có thể sử dụng trình soạn thảo plain text để kiểm tra và xóa lệnh (nếu cần):

docker run ubuntu:latest

Dấu hai chấm không có tag

Một trong những lỗi phổ biến nhất là đặt dấu hai chấm vào cuối tên image nhưng không bao gồm tag. Ví dụ, chúng ta thử lệnh sau để kéo Node:

docker pull node:

Docker mong đợi một giá trị nào đó sau dấu hai chấm, chẳng hạn như latest, 18-alpine hoặc bất kỳ tag hợp lệ nào khác. Nếu không cung cấp bất kỳ giá trị nào, tên image được coi là không đầy đủ và sẽ gây ra lỗi "Invalid Reference Format":

Để khắc phục lỗi này, hãy thêm một tag thích hợp sau dấu hai chấm để làm cho tên image đầy đủ và hợp lệ:

docker pull node:latest

Đường dẫn file hoặc mount volume có khoảng trắng

Khi bạn bao gồm một đường dẫn file có chứa khoảng trắng, đặc biệt là với các tùy chọn như -v (volume mount), Docker có thể hiểu sai các phần của đường dẫn thành những đối số riêng biệt hoặc thậm chí là một phần của tên image. Do đó, bạn có thể gặp phải những kết quả không mong muốn như hiển thị bên dưới:

docker run -v /home/user/My Folder:/app ubuntu

Để tránh điều này, hãy luôn đặt đường dẫn file có khoảng cách trong dấu ngoặc kép, như hiển thị bên dưới:

docker run -v "/home/user/My Folder:/app" ubuntu

Thay thế “/home/user/My Folder” bằng đường dẫn thực tế đến thư mục bạn muốn mount vào container.

Sử dụng biến không phù hợp

Khi làm việc với Docker, việc sử dụng biến trong các lệnh là rất phổ biến, đặc biệt là khi chỉ định phiên bản image. Tuy nhiên, nếu một biến như $VERSION không được thiết lập chính xác, Docker có thể gặp phải các vấn đề như lỗi "Invalid Reference Format".

Ví dụ, chạy lệnh sau để kéo Ubuntu từ Docker Hub:

docker pull ubuntu:$VERSION

Ở đây, $VERSION được cho là đại diện cho phiên bản image Ubuntu bạn muốn kéo. Nhưng nếu bạn chưa gán giá trị cho nó, Docker sẽ diễn giải lệnh là "docker pull ubuntu:". Điều này dẫn đến tên image không hợp lệ vì nó kết thúc bằng dấu hai chấm và thiếu tag phiên bản bắt buộc.

Để tránh điều này, hãy đảm bảo tất cả các biến được sử dụng trong lệnh được định nghĩa đúng. Trong Linux, bạn có thể đặt một biến bằng cú pháp sau.

$VERSION=latest

Sau đó, kéo phiên bản đã chỉ định bằng cách thực thi lệnh sau.

docker pull ubuntu:$VERSION

Trong CMD  Windows, bạn cần sử dụng từ khóa set để định nghĩa một biến (chẳng hạn như phiên bản), sau đó sử dụng cú pháp %VARIABLE% để tham chiếu đến nó trong các lệnh như docker pull.

set VERSION=latest
docker pull ubuntu:%VERSION%

Ở đây, $VERSION giữ giá trị gần nhất, vì vậy Docker kéo image ubuntu:latest mà không gặp bất kỳ sự cố nào. Bạn cũng có thể gán một phiên bản cụ thể, chẳng hạn như 18.04, nếu cần.

Vấn đề sao chép và dán

Đôi khi, người dùng sao chép lệnh từ các hướng dẫn hoặc tài liệu trực tuyến. Các lệnh được sao chép này có thể chứa những ký tự ẩn như khoảng trắng vô hình, dấu câu không phải tiếng Anh hoặc dấu ngoặc kép đặc biệt. Những ký tự này có thể âm thầm làm hỏng lệnh Docker của bạn.

Để tránh điều này, tốt hơn hết là bạn nên tự nhập lệnh khi có thể hoặc dán lệnh vào trình soạn thảo plain text trước để loại bỏ định dạng không mong muốn.

Giờ đây, khi đã nắm rõ những nguyên nhân phổ biến gây ra lỗi "Invalid Reference Format" trong Docker và cách khắc phục tương ứng, bạn sẽ dễ dàng tránh được sự cố này trong tương lai. Từ việc kiểm tra chữ in hoa cho đến việc đảm bảo các biến được thiết lập đúng, những mẹo đơn giản này có thể giúp bạn tiết kiệm rất nhiều thời gian và tránh được nhiều phiền toái. Nếu đã sẵn sàng khám phá thêm, bạn cũng có thể muốn tìm hiểu cách gắn tag và đẩy các image Docker tùy chỉnh của mình tới registry hoặc cách dọn dẹp những image không sử dụng để giữ cho hệ thống luôn ngăn nắp.