Google Cloud Storage “NoSuchKey”: Nguyên nhân và cách sửa

Khi đọc một object từ Google Cloud Storage (GCS) thông qua XML API, nếu object bị thiếu, hệ thống sẽ trả về lỗi XML với mã NoSuchKey. Vì XML API của GCS tương thích với S3, lỗi này trông giống hệt lỗi cùng tên của Amazon S3 — do đó, cách khắc phục dưới đây áp dụng cho cả GCS và mọi dịch vụ lưu trữ tương thích với S3.

Thông báo lỗi

<Error>
  <Code>NoSuchKey</Code>
  <Message>The specified key does not exist.</Message>
</Error>

Vì sao lỗi này xảy ra?

Ý nghĩa của lỗi rất đúng theo nghĩa đen: không có object nào tồn tại tại key (đường dẫn object) chính xác mà request của bạn yêu cầu trong bucket đó. Bản thân request hợp lệ và đã được xác thực — hệ thống lưu trữ đơn giản là không có dữ liệu để trả về. Vấn đề nằm ở chỗ object gần như luôn trông như đang tồn tại, nên phần việc thực sự là tìm hiểu vì sao key mà code yêu cầu không khớp với key đang được lưu trữ.

Cách khắc phục

Hãy xác nhận object tồn tại tại đúng key bạn đang yêu cầu, sau đó tìm và xử lý điểm không khớp:

1. Liệt kê bucket (hoặc prefix) và kiểm tra object có thực sự ở đó hay không — có thể object chưa từng được upload hoặc đã bị xóa.
2. So sánh key theo từng byte với key mà code của bạn yêu cầu. Key của object trong GCS phân biệt chữ hoa, chữ thường, và toàn bộ đường dẫn “thư mục” là một phần của key — images/hero.webp và Images/hero.webp là hai object khác nhau.
3. Kiểm tra xem key có dấu gạch chéo ở đầu hoặc dấu gạch chéo kép hay không. Một đường dẫn được tạo thành /images/hero.webp hoặc images//hero.webp sẽ trỏ đến một key không tồn tại, ngay cả khi images/hero.webp có tồn tại.
4. Đảm bảo tên bucket không vô tình bị đưa vào object key và bạn đang trỏ đến đúng bucket.
5. Nếu key chứa khoảng trắng hoặc ký tự đặc biệt, hãy xác minh key đã được mã hóa URL đúng cách cho XML API — đồng thời không bị mã hóa hai lần.
6. Nếu pipeline ghi rồi đọc ngay lập tức, hãy xác nhận thao tác ghi đã thực sự thành công trước khi đọc. GCS có tính nhất quán mạnh đối với việc đọc object, vì vậy một lần upload thành công sẽ có thể đọc ngay — lỗi NoSuchKey trong trường hợp này có nghĩa là thao tác ghi chưa hoàn tất, chứ không phải bạn cần chờ thêm.

Trên thực tế, nguyên nhân phổ biến nhất là đường dẫn được tạo khác nhau khi ghi và khi đọc (chẳng hạn prefix hoặc dấu gạch chéo ở đầu chỉ xuất hiện ở một phía). Vì vậy, hãy log chính xác key trong cả hai thao tác rồi so sánh chúng.

Đây là kiểu lỗi storage và pipeline có thể khiến bạn mất cả buổi chiều để xử lý. Công việc của tôi bao gồm xây dựng và debug các hệ thống backend cũng như tích hợp API — trong đó có cloud storage và data pipeline. Nếu cần hỗ trợ về backend hoặc tích hợp API, hãy xem các dịch vụ của Netalith hoặc liên hệ trực tiếp với tôi trên LinkedIn.