Google Cloud Storage : erreur « NoSuchKey » — causes et solutions

Lorsqu’un objet est lu depuis Google Cloud Storage (GCS) via son API XML, un objet introuvable renvoie une erreur XML avec le code NoSuchKey. Comme l’API XML de GCS est compatible avec S3, cette erreur est identique à celle renvoyée par Amazon S3 sous le même nom — les solutions ci-dessous s’appliquent donc à GCS comme à tout stockage compatible avec S3.

Le message d’erreur

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

Pourquoi cette erreur se produit-elle ?

Le sens est littéral : aucun objet n’existe à la clé exacte (le chemin de l’objet) demandée par votre requête, dans ce bucket. La requête est valide et authentifiée — le service de stockage n’a simplement rien à renvoyer. Le problème, c’est que l’objet semble presque toujours être présent. Il faut donc déterminer pourquoi la clé demandée par votre code ne correspond pas à celle réellement enregistrée.

Comment corriger le problème

Vérifiez que l’objet existe à la clé exacte demandée, puis identifiez et corrigez toute différence :

1. Répertoriez le bucket (ou le préfixe concerné) et vérifiez que l’objet s’y trouve réellement — il n’a peut-être jamais été importé ou a été supprimé.
2. Comparez la clé octet par octet avec celle demandée par votre code. Les clés d’objet GCS sont sensibles à la casse, et le chemin complet du « dossier » fait partie de la clé — images/hero.webp et Images/hero.webp sont deux objets différents.
3. Recherchez une barre oblique superflue au début ou une double barre oblique dans la clé. Un chemin construit comme /images/hero.webp ou images//hero.webp pointe vers une clé inexistante, même si images/hero.webp existe.
4. Vérifiez que le nom du bucket n’a pas été inclus par erreur dans la clé de l’objet et que vous utilisez bien le bon bucket.
5. Si la clé contient des espaces ou des caractères spéciaux, vérifiez qu’elle est correctement encodée pour l’API XML — et qu’elle n’a pas été encodée deux fois.
6. Si votre pipeline écrit un objet puis le lit immédiatement, confirmez que l’écriture a bien réussi avant la lecture. GCS offre une cohérence forte pour la lecture des objets : un import réussi est donc disponible immédiatement. Dans ce cas, une erreur NoSuchKey signifie que l’écriture n’est jamais arrivée à son terme, et non qu’il faut patienter.

En pratique, le problème le plus fréquent vient d’un chemin construit différemment lors de l’écriture et de la lecture : un préfixe ou une barre oblique initiale n’apparaît que d’un côté. Consignez donc la clé exacte lors des deux opérations et comparez-les.

C’est le genre de bug de stockage ou de pipeline auquel on peut facilement consacrer tout un après-midi. Dans le cadre de mon activité, je conçois et je débogue des systèmes backend et des intégrations d’API, notamment pour le stockage cloud et les pipelines de données. Si vous avez besoin d’aide pour un backend ou une intégration d’API, consultez les services de Netalith ou contactez-moi directement sur LinkedIn.