pallets/flask · error · ValueError

'name' may not contain a dot '.' character.

Error message

'name' may not contain a dot '.' character.

What it means

A ValueError from `Blueprint.__init__` (src/flask/sansio/blueprints.py:198-199). Flask uses the dot as the namespace separator for nested blueprints and endpoints (`parent.child.view` in `url_for`), so a dot inside a single blueprint's name would make it indistinguishable from a nesting hierarchy and corrupt endpoint resolution. This became a hard error in Flask 2.0 when nested blueprints were introduced; before that it was a deprecation warning.

Source

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

        url_prefix: str | None = None,
        subdomain: str | None = None,
        url_defaults: dict[str, t.Any] | None = None,
        root_path: str | None = None,
        cli_group: str | None = _sentinel,  # type: ignore[assignment]
    ):
        super().__init__(
            import_name=import_name,
            static_folder=static_folder,
            static_url_path=static_url_path,
            template_folder=template_folder,
            root_path=root_path,
        )

        if not name:
            raise ValueError("'name' may not be empty.")

        if "." in name:
            raise ValueError("'name' may not contain a dot '.' character.")

        self.name = name
        self.url_prefix = url_prefix
        self.subdomain = subdomain
        self.deferred_functions: list[DeferredSetupFunction] = []

        if url_defaults is None:
            url_defaults = {}

        self.url_values_defaults = url_defaults
        self.cli_group = cli_group
        self._blueprints: list[tuple[Blueprint, dict[str, t.Any]]] = []

    def _check_setup_finished(self, f_name: str) -> None:
        if self._got_registered_once:
            raise AssertionError(
                f"The setup method '{f_name}' can no longer be called on the blueprint"
                f" '{self.name}'. It has already been registered at least once, any"

View on GitHub ↗ (pinned to 6a2f545bfd)

Solutions

1. Replace the dot with another separator: `Blueprint('api_v1', __name__)`, and express the URL structure via `url_prefix='/api/v1'`.
2. If you want real hierarchy, create separate blueprints and nest them with `parent.register_blueprint(child)` — Flask joins the names with dots for you.
3. If deriving the name from a module path, take the last segment: `__name__.rsplit('.', 1)[-1]`.

Example fix

# before
bp = Blueprint("api.v1", __name__)

# after
bp = Blueprint("api_v1", __name__, url_prefix="/api/v1")

if '.' in name:
    name = name.replace('.', '_')
bp = Blueprint(name, __name__)

def is_valid_bp_name(name):
    return isinstance(name, str) and name and '.' not in name

When it happens

Trigger: `Blueprint('api.v1', __name__)` or any name containing '.', including names auto-derived from module paths like `Blueprint(__name__, __name__)` where `__name__` is 'myapp.views'.

Common situations: Trying to express versioned namespaces ('api.v1') in the name instead of using nested blueprints or url_prefix; passing `__name__` (a dotted module path) as the blueprint name; upgrading from Flask 1.x where dotted names only warned.

Related errors

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

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