pallets/flask · error · ValueError

The name ' ' is already registered for blueprint . Use…

Error message

The name '{self_name}' is already registered for {bp_desc} blueprint{existing_at}. Use 'name=' to provide a unique name.

What it means

During register(), Flask computes the final blueprint name (name_prefix.name) and checks app.blueprints for collisions. If the resolved name is already present, it raises ValueError and tells the user to pass name= to disambiguate. This supports registering the same blueprint multiple times under unique names.

Solutions

1. Pass a unique name (or name_prefix) on each registration: app.register_blueprint(bp, name_prefix='v2') or name='admin2'.
2. Register each distinct blueprint only once under its own default name.
3. Guard against double registration by checking `if bp.name not in app.blueprints`.

Example fix

// before
app.register_blueprint(admin_bp, url_prefix='/admin')
app.register_blueprint(admin_bp, url_prefix='/admin2')  # raises

// after
app.register_blueprint(admin_bp, url_prefix='/admin')
app.register_blueprint(admin_bp, url_prefix='/admin2', name='admin2')

def resolve_bp_name(app, bp, options) -> str:
    name_prefix = options.get('name_prefix', '')
    self_name = options.get('name', bp.name)
    name = f'{name_prefix}.{self_name}'.lstrip('.')
    if name in app.blueprints:
        raise ValueError(f'blueprint name {name!r} already taken; pass name=')
    return name

def bp_name_is_unique(app, name: str) -> bool:
    return name not in app.blueprints

try:
    app.register_blueprint(bp, url_prefix='/v2')
except ValueError as e:
    if 'already registered' in str(e):
        app.register_blueprint(bp, url_prefix='/v2', name='bp_v2')
    else:
        raise

When it happens

Trigger: Calling app.register_blueprint(bp) twice without a unique name/name_prefix; registering two different blueprints that resolve to the same dotted name; registering the same blueprint in a loop.

Common situations: Mounting one blueprint at multiple URL prefixes (must supply name= each time); wildcard/blueprint factories producing colliding names; reloading modules that re-run registration.

Related errors

• 'endpoint' may not contain a dot '.' character.
• 'name' may not contain a dot '.' character.
• Cannot register a blueprint on itself
• 'name' may not be empty.
• The setup method ' ' can no longer be called on the…

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

Appendix: source

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

            Nested blueprints are registered with their dotted name.
            This allows different blueprints with the same name to be
            nested at different locations.

        .. 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``.
        """
        name_prefix = options.get("name_prefix", "")
        self_name = options.get("name", self.name)
        name = f"{name_prefix}.{self_name}".lstrip(".")

        if name in app.blueprints:
            bp_desc = "this" if app.blueprints[name] is self else "a different"
            existing_at = f" '{name}'" if self_name != name else ""

            raise ValueError(
                f"The name '{self_name}' is already registered for"
                f" {bp_desc} blueprint{existing_at}. Use 'name=' to"
                f" provide a unique name."
            )

        first_bp_registration = not any(bp is self for bp in app.blueprints.values())
        first_name_registration = name not in app.blueprints

        app.blueprints[name] = self
        self._got_registered_once = True
        state = self.make_setup_state(app, options, first_bp_registration)

        if self.has_static_folder:
            state.add_url_rule(
                f"{self.static_url_path}/<path:filename>",
                view_func=self.send_static_file,  # type: ignore[attr-defined]
                endpoint="static",
            )

View on GitHub (pinned to 3596b1ab61)