Codes d'erreur Spanner

Cette page décrit les codes d'erreur Spanner et les actions recommandées pour les gérer. Les API Google, y compris Spanner, utilisent les codes d'erreur canoniques définis par google.rpc.Code.

Lorsqu'une requête Spanner aboutit, l'API renvoie un code d'état HTTP 200 OK avec les données demandées dans le corps de la réponse.

Lorsqu'une requête échoue, l'API Spanner renvoie un code d'état HTTP 4xx ou 5xx qui identifie l'échec de manière générique, ainsi qu'une réponse fournissant des informations plus spécifiques sur les erreurs ayant causé l'échec.

L'objet de la réponse contient un seul champ error dont la valeur contient les éléments suivants :

Élément Description
code Un code d'état HTTP identifiant de manière générique l'échec de la requête.
message Des informations spécifiques au sujet de la requête.
status Le code d'erreur canonique (google.rpc.Code) pour les API Google. Les codes pouvant être renvoyés par l'API Spanner sont répertoriés dans la section Codes d'erreur.

Si une requête effectuée avec un type de contenu application/x-protobuf génère une erreur, elle renvoie un message sérialisé google.rpc.Status en tant que charge utile.

Codes d'erreur

La méthode recommandée pour classer les erreurs consiste à inspecter la valeur du code d'erreur canonique (google.rpc.Code). Dans les erreurs JSON, ce code apparaît dans le champ status. Dans les erreurs application/x-protobuf, il se trouve dans le champ code.

Code d'erreur Description Action recommandée
ABORTED L'opération a été abandonnée, généralement en raison d'un problème de simultanéité, tel qu'un échec de vérification du séquenceur ou un abandon de transaction. Indique que la requête entre en conflit avec une autre requête. Pour une validation non transactionnelle :
réessayez la requête ou structurez vos entités pour réduire la contention.

Pour les requêtes faisant partie d'une validation transactionnelle :
réessayez l'intégralité de la transaction ou structurez vos entités afin de réduire la contention.
ALREADY_EXISTS L'entité qu'un client a essayé de créer existe déjà (par exemple, insertion d'une ligne avec une clé primaire existante). Ne relancez pas la requête avant d'avoir résolu le problème.
CANCELLED L'opération a été annulée, généralement par l'appelant. Effectuez une nouvelle tentative.
DEADLINE_EXCEEDED Le délai a expiré avant que l'opération puisse se terminer. Vérifiez si le délai est suffisant. Utilisez un délai correspondant au moment où une réponse est utile. Notez que pour les opérations qui modifient l'état du système, une erreur peut être renvoyée même si l'opération s'est terminée avec succès.

Pour obtenir des conseils, consultez Résoudre les erreurs de dépassement du délai.
FAILED_PRECONDITION L'opération a été rejetée, car une condition préalable à la requête n'a pas été remplie. Le champ "message" dans la réponse d'erreur fournit des informations sur la condition préalable ayant échoué. Par exemple, lire ou interroger à partir d'un code temporel qui a dépassé l'obsolescence maximale du code temporel. Ne relancez pas la requête avant d'avoir résolu le problème.
INTERNAL Le serveur a renvoyé une erreur. Certains invariants attendus par le système sous-jacent n'ont pas été respectés. N'effectuez pas de nouvelle tentative, sauf si vous comprenez la cause et la situation spécifiques de l'erreur.
INVALID_ARGUMENT Le client a spécifié une valeur non valide. Le champ "message" dans la réponse d'erreur fournit des informations au sujet de la valeur non valide. Ne relancez pas la requête avant d'avoir résolu le problème.
NOT_FOUND Indique qu'une entité demandée (par exemple, la mise à jour d'une entité ou l'interrogation d'une table ou d'une colonne) n'existe pas. Ne relancez pas la requête avant d'avoir résolu le problème.
OUT_OF_RANGE L'opération a été tentée au-delà de la plage valide. Ne relancez pas la requête avant d'avoir résolu le problème.
PERMISSION_DENIED L'utilisateur n'était pas autorisé à effectuer la requête. Ne relancez pas la requête avant d'avoir résolu le problème.
RESOURCE_EXHAUSTED Certaines ressources ont été épuisées.

Pour le plan d'administration, il est possible que le projet ait dépassé son quota ou que le système de fichiers dans son intégralité manque d'espace.

Pour le plan de données, cela peut se produire si vos nœuds Spanner sont surchargés.

Pour en savoir plus, consultez également Codes d'erreur liés aux sessions.		 Pour le plan d'administrateur, vérifiez que vous n'avez pas dépassé votre quota Spanner ou de projet. Si vous avez dépassé un quota, demandez une augmentation de quota ou attendez que le quota soit réinitialisé avant de réessayer. Configurez vos nouvelles tentatives pour utiliser l'intervalle exponentiel entre les tentatives.

Pour le plan de données, vérifiez que vos nœuds Spanner n'ont pas dépassé leur capacité. Spanner réessaie ces erreurs dans la bibliothèque cliente. Si toutes les tentatives échouent, consultez Erreurs liées au mécanisme de contrôle du flux.

 En général, si votre application rencontre des erreurs RESOURCE_EXHAUSTED, traitez la situation comme une erreur UNAVAILABLE et réessayez avec une temporisation de retransmission.
UNAUTHENTICATED La requête ne dispose pas d'identifiants d'authentification valides pour l'opération. Ne relancez pas la requête avant d'avoir résolu le problème.
UNAVAILABLE Le serveur est indisponible. Relancez la requête avec un intervalle exponentiel entre les tentatives. Notez qu'il n'est pas toujours sûr de relancer des opérations non idempotentes.
UNIMPLEMENTED L'opération n'est pas implémentée ou n'est pas prise en charge/activée dans ce service. Ne relancez pas la requête avant d'avoir résolu le problème.
UNKNOWN Le serveur a renvoyé une erreur inconnue. Les erreurs des API qui ne renvoient pas suffisamment d'informations relatives aux erreurs peuvent être converties dans cette erreur. Vérifiez que votre demande est sûre. Réessayez ensuite avec un intervalle exponentiel entre les tentatives.

Erreurs de session

Spanner utilise des sessions pour gérer les interactions entre votre application et la base de données. Les sessions représentent une connexion à la base de données et facilitent les opérations telles que les lectures et les écritures.

Voici quelques erreurs courantes liées aux sessions que votre application peut rencontrer :

Session introuvable

L'erreur Session not found se produit lorsque votre application tente d'utiliser une session qui n'existe plus. Ces erreurs peuvent se produire pour plusieurs raisons.

  • Votre application cliente peut supprimer explicitement une session. Par exemple, la fermeture d'un client de base de données dans votre code ou l'appel direct de l'API deleteSessions suppriment la session. Si vous n'utilisez pas l'une des bibliothèques clientes Spanner, créez une session lorsque cette erreur se produit. Ajoutez la nouvelle session à votre pool de sessions et supprimez la session supprimée du pool.

  • Spanner supprime également automatiquement les sessions dans certaines conditions.

    • Il supprime une session si elle reste inactive pendant plus d'une heure. Cela peut se produire dans les tâches de flux de données où le traitement en aval prend plus de temps que le délai d'inactivité de la session. Si vous utilisez une tâche Dataflow, ajoutez une opération de transformation Reshuffle après la lecture Spanner dans le pipeline Dataflow. Cela peut aider à dissocier l'opération de lecture Spanner des étapes de traitement de longue durée suivantes.

    • Spanner supprime également une session si elle date de plus de 28 jours. Si vous utilisez la bibliothèque cliente, elle gère automatiquement ces cas. Si vous n'utilisez pas l'une des bibliothèques clientes Spanner, créez une session lorsque cette erreur se produit. Ajoutez la nouvelle session à votre pool de sessions et supprimez-en la session supprimée.

  • Si vous utilisez l'une des bibliothèques clientes Spanner, la bibliothèque gère les sessions automatiquement. Si vous rencontrez cette erreur, vérifiez que votre code ne supprime pas explicitement les sessions, par exemple en fermant le client de base de données. Il peut également arriver que ce problème soit dû à un problème de gestion des sessions dans la bibliothèque cliente.

Ressource épuisée

Les erreurs RESOURCE_EXHAUSTED: No session available in the pool ou RESOURCE_EXHAUSTED: Timed out after waiting X ms for acquiring session indiquent que votre application ne peut pas acquérir de session à partir du pool de sessions. Cela se produit lorsqu'aucune session n'est disponible pour traiter les nouvelles demandes de lecture ou d'écriture.

Le tableau suivant décrit certaines raisons pouvant entraîner ces erreurs, ainsi que les actions recommandées correspondantes.

Motif Action recommandée
Toutes les sessions du pool sont utilisées. Il est possible que votre application reçoive plus de requêtes simultanées que le nombre maximal de sessions configuré. Toutes les sessions du pool sont occupées et aucune n'est disponible pour les nouvelles requêtes. Activez les sessions multiplexées. Les sessions multiplexées permettent à plusieurs transactions et lectures de partager une même session, ce qui peut réduire le nombre total de sessions requises par votre application. Vous pouvez également augmenter la configuration maxSession ou minSession dans vos paramètres du pool de sessions.
Le traitement des demandes prend beaucoup de temps. Les requêtes de lecture ou d'écriture de longue durée peuvent occuper toutes les sessions disponibles pendant de longues périodes. Si ces requêtes prennent plus de temps que le paramètre de délai avant expiration de l'acquisition de session, les nouvelles requêtes ne peuvent pas obtenir de session à partir du pool de sessions. Découvrez pourquoi vos demandes mettent du temps à être traitées. Optimisez vos requêtes ou la logique de votre application pour réduire le temps d'exécution. Vous pouvez augmenter le paramètre de délai avant expiration de l'acquisition de session. Vous pouvez également activer les sessions multiplexées pour les bibliothèques clientes éligibles afin d'améliorer l'utilisation des sessions.
Des fuites de sessions ont été détectées. Une fuite de session se produit lorsque votre application extrait une session du pool, mais ne la renvoie pas après avoir terminé la requête. Cela se produit généralement lorsque les itérateurs ou les ensembles de résultats ne sont pas fermés correctement dans votre code. Si toutes les sessions fuient, aucune session n'est disponible pour les nouvelles requêtes. Déboguez le code de votre application pour identifier et corriger les fuites de session. Assurez-vous que votre code ferme correctement tous les itérateurs et ensembles de résultats. Pour en savoir plus, consultez Solutions de détection des fuites de session. Vous pouvez également utiliser la fonctionnalité de nettoyage automatique des fuites de session pour configurer votre pool de sessions afin de résoudre automatiquement les transactions inactives.
La création de sessions est lente. La création de sessions est une opération coûteuse en termes de calcul. Les bibliothèques clientes envoient des API BatchCreateSessions pour créer des sessions initiales (en fonction de la configuration minSession) et des API CreateSessions pour les sessions supplémentaires (jusqu'à maxSession). Si la création de session prend plus de temps que le paramètre de délai d'acquisition de session, les nouvelles requêtes peuvent expirer en attendant les sessions. Vérifiez la latence des appels d'API BatchCreateSessions et CreateSessions. La lenteur de la création de sessions peut être due à des problèmes de ressources côté Spanner ou à un grand nombre d'opérations de création de sessions simultanées.

Erreurs liées au mécanisme de contrôle de flux

Spanner peut activer son mécanisme de contrôle du flux pour se protéger contre la surcharge dans les conditions suivantes :

  • L'utilisation du processeur est élevée sur le nœud Spanner. Si vous pensez que votre requête entraîne une utilisation intensive du processeur, vous pouvez utiliser les métriques d'utilisation du processeur pour examiner le problème.
  • Il peut y avoir des points chauds, ce qui augmente le temps de traitement de la demande. Si vous pensez que votre requête est à l'origine de hotspots, consultez Identifier les hotspots dans votre base de données pour examiner le problème. Pour en savoir plus, consultez Key Visualizer.

Le mécanisme de contrôle du flux est compatible avec les bibliothèques clientes suivantes :

Le temps global nécessaire à l'exécution de la requête n'augmentera pas en raison de l'utilisation du mécanisme de contrôle du flux. Sans ce mécanisme, Spanner attend avant de traiter la requête et finit par renvoyer une erreur DEADLINE_EXCEEDED.

Lorsque le mécanisme de contrôle du flux est actif, Spanner renvoie les requêtes au client pour qu'il les réessaie. Si la nouvelle tentative consomme l'intégralité du délai fourni par l'utilisateur, le client reçoit une erreur RESOURCE_EXHAUSTED. Cette erreur est renvoyée si Spanner estime que le temps de traitement de la requête est trop long. L'erreur propage le contrôle du flux et Spanner renvoie la requête au client, au lieu d'accumuler les tentatives en interne. Cela permet à Spanner d'éviter d'accumuler une consommation de ressources supplémentaire.