Fix TypeError: send_welcome_email() got an unexpected keyword argument 'signal' in Django

This error means your signal receiver function signature does not accept the keyword arguments Django passes automatically, including sender, signal, and instance. Fix it by adding **kwargs to your receiver function signature so it accepts all keyword arguments that Django's signal dispatch sends.

Reading the Stack Trace

Here's what each line means:

• File "/venv/lib/python3.11/site-packages/django/db/models/base.py", line 862, in save_base: Django's Model.save() fires the post_save signal after successfully saving the instance to the database.
• File "/venv/lib/python3.11/site-packages/django/dispatch/dispatcher.py", line 177, in <listcomp>: Django's signal dispatcher calls each receiver with signal, sender, and additional keyword arguments.
• TypeError: send_welcome_email() got an unexpected keyword argument 'signal': The receiver function does not accept the 'signal' keyword argument that Django always passes to signal receivers.

Common Causes

from django.db.models.signals import post_save
from django.dispatch import receiver
from django.contrib.auth.models import User

@receiver(post_save, sender=User)
def send_welcome_email(instance):
    # Missing: sender, **kwargs
    send_email(instance.email, 'Welcome!')

# accounts/signals.py — file exists but never imported
@receiver(post_save, sender=User)
def send_welcome_email(sender, instance, **kwargs):
    send_email(instance.email, 'Welcome!')

# accounts/apps.py — missing ready() method
class AccountsConfig(AppConfig):
    name = 'accounts'

@receiver(post_save, sender=User)
def update_profile(sender, instance, **kwargs):
    instance.profile.last_active = timezone.now()
    instance.save()  # Triggers post_save again → infinite loop

The Fix

Add sender, created, and **kwargs to the receiver signature. Check the created flag to only send the email on new user creation, not every save. Import the signals module in the app's ready() method to ensure the receiver is connected.

from django.db.models.signals import post_save
from django.dispatch import receiver
from django.contrib.auth.models import User

@receiver(post_save, sender=User)
def send_welcome_email(instance):
    send_email(instance.email, 'Welcome!')

from django.db.models.signals import post_save
from django.dispatch import receiver
from django.contrib.auth.models import User

@receiver(post_save, sender=User)
def send_welcome_email(sender, instance, created, **kwargs):
    if created:
        send_email(instance.email, 'Welcome!')

# accounts/apps.py
class AccountsConfig(AppConfig):
    default_auto_field = 'django.db.models.BigAutoField'
    name = 'accounts'

    def ready(self):
        import accounts.signals  # noqa: F401

Testing the Fix

import pytest
from unittest.mock import patch
from django.test import TestCase
from django.contrib.auth.models import User


class TestWelcomeEmailSignal(TestCase):
    @patch('accounts.signals.send_email')
    def test_welcome_email_sent_on_user_creation(self, mock_send):
        user = User.objects.create_user('newuser', email='new@example.com', password='pass')
        mock_send.assert_called_once_with('new@example.com', 'Welcome!')

    @patch('accounts.signals.send_email')
    def test_welcome_email_not_sent_on_update(self, mock_send):
        user = User.objects.create_user('existing', email='old@example.com', password='pass')
        mock_send.reset_mock()
        user.first_name = 'Updated'
        user.save()
        mock_send.assert_not_called()

    @patch('accounts.signals.send_email')
    def test_signal_does_not_crash_on_save(self, mock_send):
        mock_send.side_effect = Exception('SMTP error')
        # Should not crash user creation
        try:
            User.objects.create_user('test', email='t@example.com', password='pass')
        except Exception:
            pytest.fail('Signal error should not prevent user creation')

Run your tests:

pytest

Pushing Through CI/CD

git checkout -b fix/signal-receiver-kwargs,git add accounts/signals.py accounts/apps.py,git commit -m "fix: add correct signature to post_save signal receiver",git push origin fix/signal-receiver-kwargs

Your CI config should look something like this:

name: CI
on:
  pull_request:
    branches: [main]
jobs:
  test:
    runs-on: ubuntu-latest
    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 to confirm the signal fires correctly.
2. Open a pull request with the signal fix and apps.py changes.
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 welcome emails are sent in staging.

Frequently Asked Questions