pallets/flask · error · ValueError

Cannot register a blueprint on itself

Error message

Cannot register a blueprint on itself

What it means

register_blueprint on a Scaffold checks `if blueprint is self` and raises ValueError to prevent infinite recursion during registration, since registering a blueprint on itself would create a self-referential registration cycle.

Solutions

1. Skip self-registration: if blueprint is not bp: bp.register_blueprint(blueprint).
2. Fix the registration list/logic so a blueprint is never both parent and child.
3. Validate the input collection before the registration loop.

Example fix

// before
for child in blueprints:
    bp.register_blueprint(child)  # child may equal bp

// after
for child in blueprints:
    if child is not bp:
        bp.register_blueprint(child)

def safe_register(parent, child, options):
    if child is parent:
        raise ValueError('cannot register blueprint on itself')
    parent.register_blueprint(child, **options)

def is_not_self(parent, child) -> bool:
    return child is not parent

When it happens

Trigger: Calling bp.register_blueprint(bp); a generic loop that pairs blueprints from a list with themselves; programmatic registration where the parent and child reference resolve to the same object.

Common situations: Automated blueprint auto-discovery that accidentally registers a blueprint as its own child; refactoring a blueprint hierarchy that left a self-reference; copy-paste error.

Related errors

• 'endpoint' may not contain a dot '.' character.
• 'name' may not be empty.
• 'name' may not contain a dot '.' character.
• 'view_func' name may not contain a dot '.' character.
• ' ' is not a subclass of Exception. Handlers can only be…

AI-assisted analysis of pallets/flask@3596b1ab61 (2026-08-11). Data as JSON: /api/errors/5ce18a7d043f8c7a. Report an issue: GitHub.

Appendix: source

Thrown at src/flask/sansio/blueprints.py:270

        """
        return BlueprintSetupState(self, app, options, first_registration)

    @setupmethod
    def register_blueprint(self, blueprint: Blueprint, **options: t.Any) -> None:
        """Register a :class:`~flask.Blueprint` on this blueprint. Keyword
        arguments passed to this method will override the defaults set
        on the blueprint.

        .. versionchanged:: 2.0.1
            The ``name`` option can be used to change the (pre-dotted)
            name the blueprint is registered with. This allows the same
            blueprint to be registered multiple times with unique names
            for ``url_for``.

        .. versionadded:: 2.0
        """
        if blueprint is self:
            raise ValueError("Cannot register a blueprint on itself")
        self._blueprints.append((blueprint, options))

    def register(self, app: App, options: dict[str, t.Any]) -> None:
        """Called by :meth:`Flask.register_blueprint` to register all
        views and callbacks registered on the blueprint with the
        application. Creates a :class:`.BlueprintSetupState` and calls
        each :meth:`record` callback with it.

        :param app: The application this blueprint is being registered
            with.
        :param options: Keyword arguments forwarded from
            :meth:`~Flask.register_blueprint`.

        .. versionchanged:: 2.3
            Nested blueprints now correctly apply subdomains.

        .. versionchanged:: 2.1
            Registering the same blueprint with the same name multiple

View on GitHub (pinned to 3596b1ab61)