django/django · error · NotImplementedError

subclasses of LabelCommand must provide a handle_label() met

Error message

subclasses of LabelCommand must provide a handle_label() method

What it means

Raised by LabelCommand.handle_label (django/core/management/base.py:716) as a NotImplementedError because LabelCommand delegates per-label work to handle_label, which is abstract. Subclasses must override it; the base method exists only to fail loudly. It fires when a LabelCommand subclass is invoked without overriding this method and at least one label argument is provided.

Source

Thrown at django/core/management/base.py:716

            self.missing_args_message = self.missing_args_message % self.label

    def add_arguments(self, parser):
        parser.add_argument("args", metavar=self.label, nargs="+")

    def handle(self, *labels, **options):
        output = []
        for label in labels:
            label_output = self.handle_label(label, **options)
            if label_output:
                output.append(label_output)
        return "\n".join(output)

    def handle_label(self, label, **options):
        """
        Perform the command's actions for ``label``, which will be the
        string as given on the command line.
        """
        raise NotImplementedError(
            "subclasses of LabelCommand must provide a handle_label() method"
        )

View on GitHub (pinned to ae25a40be0)

Solutions

1. Implement def handle_label(self, label, **options): in your LabelCommand subclass.
2. If the labels should be installed apps, subclass AppCommand and implement handle_app_config instead.
3. Confirm exact method name and signature (handle_label, with label as first positional arg).

Example fix

# before
class Command(LabelCommand):
    label = 'filename'
# after
class Command(LabelCommand):
    label = 'filename'
    def handle_label(self, label, **options):
        self.stdout.write('processing %s' % label)

def label_command_implemented(cmd_cls):
    return callable(getattr(cmd_cls, 'handle_label', None)) and \
           cmd_cls.handle_label is not LabelCommand.handle_label

When it happens

Trigger: Subclassing LabelCommand (e.g. for a command operating on file paths or other string labels) but not implementing handle_label(self, label, **options), then running the command with one or more label arguments.

Common situations: Scaffolding a new LabelCommand and leaving the method unimplemented; renaming it; confusing it with AppCommand's handle_app_config.

Related errors

• subclasses of BaseCommand must provide a handle() method
• Subclasses of AppCommand must provide a handle_app_config()
• aborted
• user '%s' does not exist
• Aborting password change for user '%s' after %s attempts

AI-assisted analysis of django/django@ae25a40be0 (2026-08-06). Data as JSON: /api/errors/37ca65bae354d4ec. Report an issue: GitHub.