pallets/flask · error · ValueError

The name '{self_name}' is already registered for {bp_desc} b

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

A ValueError from `Blueprint.register` (src/flask/sansio/blueprints.py:306-314), raised while an app (or parent blueprint) mounts this blueprint. The final registered name — `name_prefix + '.' + (options['name'] or self.name)` — must be unique in `app.blueprints` because it namespaces endpoints for `url_for`. Since Flask 2.1, registering the same name twice is a hard error; the message distinguishes whether the collision is with 'this' (same object registered twice) or 'a different' blueprint that happens to share the name.

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 6a2f545bfd)

Solutions

1. If mounting the same blueprint multiple times is intentional, give each registration a unique name: `app.register_blueprint(bp, url_prefix='/v2', name='api_v2')` — endpoints then use that name in `url_for`.
2. If it's accidental double registration, remove the duplicate call — check for `create_app()` running twice or registration at both module import and factory time.
3. If two distinct blueprints collide, rename one at construction or pass `name=` at registration.

Example fix

# before
app.register_blueprint(api, url_prefix="/v1")
app.register_blueprint(api, url_prefix="/v2")  # ValueError

# after
app.register_blueprint(api, url_prefix="/v1")
app.register_blueprint(api, url_prefix="/v2", name="api_v2")

if bp.name in app.blueprints:
    app.register_blueprint(bp, name=f'{bp.name}_2', url_prefix='/v2')
else:
    app.register_blueprint(bp)

def bp_name_free(app, name):
    return name not in app.blueprints

try:
    app.register_blueprint(bp)
except ValueError as e:
    if 'already registered' in str(e):
        app.register_blueprint(bp, name=f'{bp.name}_{suffix}')

When it happens

Trigger: Calling `app.register_blueprint(bp)` twice for the same object without a distinguishing `name=`; registering two different Blueprint objects constructed with the same name string; nested registration where `name_prefix` makes two children resolve to the same dotted name; a `create_app()` or module-level registration executing twice (double import, test re-using a module-level app).

Common situations: Test suites registering blueprints onto a shared app across tests; wanting the same blueprint mounted at two URL prefixes (supported, but each mount needs a unique `name=`); two plugins/extensions each shipping a blueprint named e.g. 'auth'; upgrading from Flask <2.1 where silent double registration was tolerated.

Related errors

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

AI-assisted analysis of pallets/flask@6a2f545bfd (2026-07-31). Data as JSON: /data/errors/6031740d93dbafef.json. Report an issue: GitHub ↗.