Introduction
L’erreur Odoo « Duplicate Key Value Violates Unique Constraint » survient quand une insertion ou une mise à jour tente d’enfreindre une règle d’unicité définie au niveau de la base de données.
C’est un message d’erreur généré par PostgreSQL au niveau de la base et il se manifeste généralement dans :
- les journaux serveur
- les échecs d’importation
- les réponses d’API
- les montées de version de modules
- les scripts de migration de données
Concrètement, le message ressemble souvent à ceci :
psycopg2.errors.UniqueViolation: duplicate key value violates unique constraint "res_partner_email_uniq" DETAIL: Key (email)=(john@example.com) already exists.
Ce guide détaille les raisons possibles de l’erreur et présente des méthodes sûres pour la résoudre sans compromettre l’intégrité des données.
Qu’est-ce qu’une contrainte d’unicité dans Odoo ?
Une contrainte d’unicité impose que certains champs restent exclusifs — aucun doublon accepté.
Dans Odoo, l’unicité peut être appliquée via plusieurs mécanismes :
- des contraintes SQL explicites
- la définition _sql_constraints dans les modèles
- des index uniques au niveau de la base de données
Par exemple :
_sql_constraints = [
('email_unique', 'unique(email)', 'Email must be unique.')
]
Concrètement, cela empêche que deux enregistrements partagent la même adresse e‑mail.
Si on tente d’insérer un doublon, PostgreSQL rejette l’opération.
Causes fréquentes des erreurs « duplicate key constraint »
1. Création d’un enregistrement déjà existant
Tentatives typiques :
- créer un partenaire avec une adresse e‑mail déjà utilisée
- créer un produit avec une référence interne déjà prise
- créer un utilisateur avec un login déjà existant
Dans ces cas, Odoo bloque l’opération pour respecter la contrainte.
2. API ou intégration qui génère des doublons
Les systèmes externes peuvent involontairement :
- recréer des clients déjà présents
- renvoyer la même commande plusieurs fois
- dupliquer des fiches produit
parce qu’ils n’effectuent pas de vérification préalable de l’existence du record.
C’est un scénario fréquent lors d’intégrations mal conçues.
3. Import de lignes en double
Des imports CSV contenant des valeurs répétées sur des champs uniques entraînent des échecs.
Par exemple :
Par exemple deux lignes avec la même adresse e‑mail ou la même référence externe.
4. Migration et ajout d’une nouvelle contrainte d’unicité
Si une mise à jour de module introduit une contrainte unique alors que des doublons existent déjà, la migration plante.
5. Mauvaise gestion des External IDs
Si les intégrations ignoreront les External IDs et injectent des enregistrements bruts, des doublons peuvent apparaître.
Des stratégies de mapping correctes empêchent ce type de problème.
6. Manipulations directes en base
Des inserts SQL directs contournent parfois les validations de l’ORM mais restent soumis aux contraintes au niveau de PostgreSQL.
Comment corriger l’erreur de clé dupliquée dans Odoo
Étape 1 – Identifier le nom de la contrainte
Le message d’erreur indique la contrainte concernée :
duplicate key value violates unique constraint "res_partner_email_uniq"
Ainsi vous savez quel champ ou index est en cause.
Étape 2 – Localiser l’enregistrement en double
Recherchez dans le modèle la valeur dupliquée.
Par exemple :
Par exemple, recherchez l’adresse e‑mail incriminée dans res.partner.
Ensuite, prenez une décision sur le traitement :
- mettre à jour l’enregistrement existant
- fusionner les doublons
- supprimer l’entrée incorrecte
Étape 3 – Adapter la logique d’intégration
Si l’erreur vient d’une API :
- implémentez un comportement « search before create »
- faites une recherche pour vérifier l’existence d’un enregistrement
- préférez la mise à jour plutôt que la création aveugle
Cela évite des échecs répétés côté base.
Étape 4 – Nettoyer les doublons avant migration
Quand une migration échoue à cause de doublons :
- identifiez les enregistrements dupliqués
- fusionnez‑les ou supprimez les redondances
- puis relancez la migration
Ne supprimez jamais la contrainte sans d’abord corriger les données.
Étape 5 – Utiliser les External IDs pour synchroniser les données
Plutôt que de vous fier aux IDs internes :
- employez des External IDs cohérents
- maintenez un mapping stable entre systèmes
- évitez les insertions aveugles
Des stratégies de synchronisation structurées réduisent nettement les erreurs de clé dupliquée.
Étape 6 – Éviter les inserts SQL directs
Favorisez toujours l’ORM Odoo pour créer des enregistrements.
L’ORM applique des validations que le SQL manuel ne fait pas automatiquement.
Comment éviter les erreurs de clé dupliquée
- Validez les données avant insertion
- Mettez en place le modèle « search‑before‑create »
- Utilisez systématiquement les External IDs
- Nettoyez régulièrement les données héritées
- Surveillez les journaux d’intégration
- N’esquivez pas l’ORM sans nécessité
Les contraintes d’unicité protègent l’intégrité des données. L’objectif est de résoudre les doublons à la source plutôt que de désactiver ces règles.
Comment Dasolo empêche la duplication de données à grande échelle
Les erreurs de type duplicate key signalent souvent l’absence de garde‑fous dans les flux de création de données. Qu’elles proviennent d’une saisie manuelle, d’un import ou d’une API, ces erreurs révèlent en général l’absence d’une logique idempotente ou d’une validation suffisante avant création.
Chez Dasolo, nous réduisons les risques de duplication en nous concentrant sur :
- des règles claires pour les champs uniques
- une logique « search‑before‑create » dans les intégrations
- une gestion contrôlée des External IDs
- des validations structurées lors des imports
- une surveillance continue des flux de synchronisation
Une gouvernance des données rigoureuse empêche la prolifération des doublons et préserve la cohérence de la base.
Conclusion
L’erreur Odoo « Duplicate Key Value Violates Unique Constraint » survient quand une opération tente d’insérer ou de modifier une valeur qui doit rester unique. La base bloque l’action pour protéger l’intégrité, mais la cause racine est souvent une validation ou une synchronisation insuffisante.
En appliquant systématiquement le pattern « search‑before‑create », en nettoyant les doublons hérités et en définissant des stratégies d’unicité cohérentes, les développeurs peuvent éviter la répétition de ces violations. Protéger les champs uniques est vital pour garder un environnement Odoo fiable et scalable.