Fix IntegrityError: UNIQUE constraint failed: accounts_user.email in Django

This error means a database insert or update tried to save a duplicate value in a column with a unique constraint. Fix it by validating uniqueness in the form or serializer before saving, using get_or_create() instead of create(), or handling the IntegrityError with a try/except block that returns a user-friendly error message.

Reading the Stack Trace

Here's what each line means:

• File "/app/accounts/views.py", line 23, in register: The registration view calls create_user without first checking if the email already exists in the database.
• File "/venv/lib/python3.11/site-packages/django/contrib/auth/models.py", line 155, in _create_user: Django's UserManager._create_user calls save() which triggers the database INSERT.
• django.db.utils.IntegrityError: UNIQUE constraint failed: accounts_user.email: The database rejected the INSERT because another row already has this email address.

Common Causes

def register(request):
    if request.method == 'POST':
        form = RegistrationForm(request.POST)
        if form.is_valid():
            user = User.objects.create_user(
                username=form.cleaned_data['username'],
                email=form.cleaned_data['email'],
                password=form.cleaned_data['password'],
            )
            return redirect('login')

class RegistrationForm(forms.Form):
    username = forms.CharField(max_length=150)
    email = forms.EmailField()
    password = forms.CharField(widget=forms.PasswordInput)
    # No clean_email method to check uniqueness

def register(request):
    email = request.POST['email']
    if not User.objects.filter(email=email).exists():  # Race condition
        User.objects.create_user(email=email, ...)

The Fix

Add a clean_email method to the form that validates uniqueness before saving, and wrap create_user in a try/except IntegrityError as a safety net against race conditions. This provides a user-friendly error message instead of a 500 server error.

def register(request):
    if request.method == 'POST':
        form = RegistrationForm(request.POST)
        if form.is_valid():
            user = User.objects.create_user(
                username=form.cleaned_data['username'],
                email=form.cleaned_data['email'],
                password=form.cleaned_data['password'],
            )
            return redirect('login')
    else:
        form = RegistrationForm()
    return render(request, 'register.html', {'form': form})

from django.db import IntegrityError

class RegistrationForm(forms.Form):
    username = forms.CharField(max_length=150)
    email = forms.EmailField()
    password = forms.CharField(widget=forms.PasswordInput)

    def clean_email(self):
        email = self.cleaned_data['email']
        if User.objects.filter(email=email).exists():
            raise forms.ValidationError('A user with this email already exists.')
        return email

def register(request):
    if request.method == 'POST':
        form = RegistrationForm(request.POST)
        if form.is_valid():
            try:
                user = User.objects.create_user(
                    username=form.cleaned_data['username'],
                    email=form.cleaned_data['email'],
                    password=form.cleaned_data['password'],
                )
                return redirect('login')
            except IntegrityError:
                form.add_error('email', 'A user with this email already exists.')
    else:
        form = RegistrationForm()
    return render(request, 'register.html', {'form': form})

Testing the Fix

import pytest
from django.test import TestCase, Client
from django.contrib.auth.models import User


class TestRegistration(TestCase):
    def setUp(self):
        self.client = Client()
        User.objects.create_user('existing', email='taken@example.com', password='pass')

    def test_register_with_duplicate_email_shows_error(self):
        response = self.client.post('/register/', {
            'username': 'newuser',
            'email': 'taken@example.com',
            'password': 'securepass123',
        })
        assert response.status_code == 200
        self.assertContains(response, 'already exists')

    def test_register_with_unique_email_succeeds(self):
        response = self.client.post('/register/', {
            'username': 'newuser',
            'email': 'new@example.com',
            'password': 'securepass123',
        })
        assert response.status_code == 302
        assert User.objects.filter(email='new@example.com').exists()

    def test_form_clean_email_rejects_duplicate(self):
        from accounts.forms import RegistrationForm
        form = RegistrationForm(data={
            'username': 'another',
            'email': 'taken@example.com',
            'password': 'securepass123',
        })
        assert not form.is_valid()
        assert 'email' in form.errors

Run your tests:

pytest

Pushing Through CI/CD

git checkout -b fix/integrity-error-duplicate-email,git add accounts/views.py accounts/forms.py accounts/tests/,git commit -m "fix: validate email uniqueness before user creation",git push origin fix/integrity-error-duplicate-email

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:15
        env:
          POSTGRES_DB: test_db
          POSTGRES_USER: postgres
          POSTGRES_PASSWORD: postgres
        ports:
          - 5432:5432
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
          cache: 'pip'
      - run: pip install -r requirements.txt
      - run: pytest --tb=short -q

The Full Manual Process: 18 Steps

Here's every step you just went through to fix this one bug:

1. Notice the error alert or see it in your monitoring tool
2. Open the error dashboard and read the stack trace
3. Identify the file and line number from the stack trace
4. Open your IDE and navigate to the file
5. Read the surrounding code to understand context
6. Reproduce the error locally
7. Identify the root cause
8. Write the fix
9. Run the test suite locally
10. Fix any failing tests
11. Write new tests covering the edge case
12. Run the full test suite again
13. Create a new git branch
14. Commit and push your changes
15. Open a pull request
16. Wait for code review
17. Merge and deploy to production
18. Monitor production to confirm the error is resolved

Total time: 30-60 minutes. For one bug.

pip install bugstack

import bugstack

bugstack.init(api_key=os.environ["BUGSTACK_API_KEY"])

Deploying the Fix (Manual Path)

1. Run the full test suite locally including duplicate email tests.
2. Open a pull request with the form validation and error handling.
3. Wait for CI checks to pass on the PR.
4. Have a teammate review and approve the PR.
5. Merge to main and verify registration works correctly in staging.

Frequently Asked Questions