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é annulé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 en savoir plus sur les erreurs Database schema has changed, consultez Erreur "Le schéma de la base de données a changé".		 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 réellement 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é refusé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, la lecture ou l'interrogation à 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 nouvelles tentatives, sauf si vous comprenez la cause et les circonstances 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 de flux.

 En général, si votre application rencontre des erreurs RESOURCE_EXHAUSTED, traitez la situation comme une erreur UNAVAILABLE et réessayez avec un intervalle exponentiel entre les tentatives.
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 que relancer des opérations non idempotentes peut présenter des risques.
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 sur les erreurs peuvent être converties dans cette erreur. Vérifiez que votre demande est sécurisée. Réessayez ensuite avec un intervalle exponentiel entre les tentatives.

Erreur "Le schéma de la base de données a changé"

Un message d'erreur ABORTED semblable à l'un des suivants peut s'afficher :

  • Database schema has changed
  • Transaction aborted. Database schema probably changed during transaction, retry may succeed.

Ces erreurs se produisent généralement lorsqu'une mise à jour du schéma interrompt la transaction. Toutefois, d'autres raisons peuvent également les déclencher sans mise à jour explicite du schéma. Par exemple, un état interne temporaire, tel qu'un schéma client obsolète lors d'un commit de transaction, peut déclencher cette erreur.

Comme pour les autres erreurs ABORTED, gérez cette erreur en réessayant l'ensemble de la transaction.

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-en la session supprimée.

  • 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 un job 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û à une erreur dans la gestion des sessions de 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 requêtes 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 de 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 pour l'acquisition de session, les nouvelles requêtes ne peuvent pas obtenir de session à partir du pool de sessions. Déterminez 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 traité 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 de 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 de 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 de 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 de 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 de flux et Spanner relance 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.