pallets/flask · error · ValueError

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

Error message

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

What it means

Blueprint name cannot contain '.' because Flask uses dot as a separator between blueprint name and endpoint (e.g. 'bp.view') and between name_prefix and name. A dot in the name would corrupt endpoint resolution and url_for. The constructor raises ValueError on `if '.' in name`.

Solutions

1. Use the leaf module name: __name__.split('.')[-1] or just a plain identifier like 'admin'.
2. Strip or replace dots before constructing: name.replace('.', '_').
3. If you need hierarchical names, use the name_prefix option at registration time instead of dots in the name.

Example fix

// before
bp = Blueprint(__name__)  # __name__ == 'myapp.admin.blueprint'

// after
bp = Blueprint(__name__.split('.')[-1])  # 'blueprint'

def validate_bp_name(name: str) -> str:
    if '.' in name:
        raise ValueError('Blueprint name must not contain a dot')
    return name

def is_bp_name_dot_free(name) -> bool:
    return isinstance(name, str) and '.' not in name

When it happens

Trigger: Passing Blueprint('my.blueprint'); deriving the name from a dotted module path without splitting; concatenating names with dots.

Common situations: Using __name__ (dotted import path) directly as the blueprint name instead of the leaf; building names from f-strings with dots; migrating code that previously allowed dots.

Related errors

• 'endpoint' may not contain a dot '.' character.
• Cannot register a blueprint on itself
• 'name' may not be empty.
• The name ' ' is already registered for blueprint . Use…
• 'view_func' name may not contain a dot '.' character.

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

Appendix: 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 3596b1ab61)