Introductie
De foutmelding Odoo “Duplicate Key Value Violates Unique Constraint” treedt op zodra het systeem probeert een record toe te voegen of bij te werken met een waarde die volgens de database uniek moet zijn.
Dit is een database-niveau constraint fout die door PostgreSQL wordt gegenereerd en verschijnt meestal in:
- Serverlogs
- Importfouten
- API-responses
- Module-upgrades
- Data-migratiescripts
De fout ziet er doorgaans zo uit:
psycopg2.errors.UniqueViolation: duplicate key value violates unique constraint "res_partner_email_uniq" DETAIL: Key (email)=(john@example.com) already exists.
In deze handleiding leggen we uit waarom die fout optreedt en hoe je ze correct oplost zonder de dataintegriteit te compromitteren.
Wat is een unieke constraint in Odoo?
Een unieke constraint zorgt ervoor dat bepaalde velden geen dubbele waarden kunnen bevatten.
In Odoo kun je uniciteit afdwingen via:
- SQL-constraints
- _sql_constraints in modeldefinities
- Database-level unieke indexen
Voorbeeld:
_sql_constraints = [
('email_unique', 'unique(email)', 'Email must be unique.')
]
Dat betekent dat twee records niet hetzelfde e-mailadres mogen hebben.
Bij het invoegen van een duplicaat weigert PostgreSQL de bewerking.
Veelvoorkomende oorzaken van 'duplicate key' fouten
1. Aanmaken van een record dat al bestaat
Wanneer je probeert aan te maken:
- Een partner met een bestaand e-mailadres
- Een product met een bestaand intern referentienummer
- Een gebruiker met een bestaande login
zal Odoo de actie blokkeren.
2. API of integratie maakt dubbele records aan
Externe systemen kunnen proberen om:
- Bestaande klanten opnieuw aan te maken
- Eenzelfde bestelling opnieuw door te sturen
- Producten dubbel te importeren
zonder eerst te controleren of het record al bestaat.
Dit is een veelvoorkomend integratieprobleem.
3. Importeren van dubbele rijen
CSV-imports met dubbele waarden in unieke velden zullen falen.
Voorbeeld:
Bijvoorbeeld twee rijen met hetzelfde e-mailadres of dezelfde externe referentie.
4. Migratie die een nieuwe unieke constraint toevoegt
Als een module-upgrade een nieuwe unieke constraint introduceert en de bestaande data bevat duplicaten, dan mislukt de migratie.
5. Onjuist omgaan met externe ID's
Als integraties externe ID's negeren en blind inserts doen, ontstaan er gemakkelijk duplicaten.
Een correcte koppelstrategie voorkomt dit probleem.
6. Handmatige databasebewerkingen
Rechtstreekse SQL-inserts kunnen ORM-validatie omzeilen maar zullen alsnog de database-constraints triggeren.
Hoe los je de Odoo 'duplicate key constraint' fout op?
Stap 1 – Bepaal de naam van de constraint
Het foutbericht geeft welke constraint het betreft:
duplicate key value violates unique constraint "res_partner_email_uniq"
Daaraan kun je zien welk veld de duplicaatwaarde bevat.
Stap 2 – Vind het duplicaatrecord
Zoek in het betreffende model naar de gedupliceerde waarde.
Voorbeeld:
Controleer bijvoorbeeld op het e-mailadres in res.partner.
Bepaal vervolgens of je:
- het bestaande record bijwerkt,
- records samenvoegt,
- of de foute invoer verwijdert.
Stap 3 – Pas de integratielogica aan
Als de fout door een API-integratie komt:
- Implementeer een “zoek vóór toevoegen” patroon,
- gebruik een zoekopdracht om bestaande records te vinden,
- en werk die records bij in plaats van telkens nieuwe te maken.
Dat voorkomt herhaalde foutmeldingen.
Stap 4 – Maak duplicaten schoon vóór migratie
Als een migratie faalt door duplicaten:
- identificeer de dubbele records,
- sla ze samen of verwijder overbodige items,
- en voer de migratie opnieuw uit.
Verwijder nooit een constraint zonder eerst de data op te schonen.
Stap 5 – Gebruik externe ID's voor data-synchronisatie
In plaats van te vertrouwen op interne database-ID's:
- gebruik externe ID's,
- houd de mapping consistent,
- en voorkom blind inserts.
Gestructureerde synchronisaties verminderen aanzienlijk het aantal duplicate key fouten.
Stap 6 – Vermijd directe SQL-inserts
Gebruik altijd de Odoo ORM voor het aanmaken van records.
De ORM verwerkt validatie veiliger dan handmatige SQL-bewerkingen.
Hoe voorkom je duplicate key fouten
- Valideer data voorafgaand aan invoer,
- pas het “search-before-create”-patroon toe,
- gebruik externe ID's consequent,
- schoon legacy-data periodiek op,
- en monitor integratielogs continu.
- Vermijd het omzeilen van de ORM.
Unieke constraints bestaan om de dataintegriteit te beschermen. Het doel is duplicaten zorgvuldig op te lossen in plaats van constraints uit te schakelen.
Hoe Dasolo duplicatie op schaal voorkomt
Fouten over duplicate key constraints wijzen meestal op ontbrekende waarborgen in de aanmaakprocessen. Of het nu handmatige invoer, imports of API-koppelingen betreft: vaak is er geen idempotente logica of voldoende validatie vóór het creëren van records.
Bij Dasolo beperken we duplicatierisico's door te focussen op:
- Duidelijke strategieën voor unieke velden,
- Search-before-create logica in integraties,
- Gestructureerd beheer van externe ID's,
- Valideren van imports volgens regels,
- En continue monitoring van synchronisatiestromen.
Een strikte aanpak van datagovernance voorkomt ongecontroleerde duplicatie en bewaart de consistentie van de database.
Conclusie
De Odoo-fout “Duplicate Key Value Violates Unique Constraint” verschijnt wanneer een bewerking probeert een record aan te maken of te wijzigen met een waarde die uniek moet blijven. De database blokkeert de handeling om integriteit te waarborgen, maar de oorzaak zit vaak in onvoldoende validatie of synchronisatielogica.
Door search-before-create patronen toe te passen, legacy-duplicaten op te ruimen en consequente uniciteitsstrategieën af te dwingen, kunnen ontwikkelaars herhaalde constraint-gebreken voorkomen. Het beschermen van unieke datavelden is cruciaal voor betrouwbare en schaalbare Odoo-omgevingen.