reflex-dev/reflex · error · ValueError

Route part `{part}` with argument is not valid. Reflex only

Error message

Route part `{part}` with argument is not valid. Reflex only supports argument names that start with an alphabetic character or underscore, followed by alphanumeric characters or underscores.

What it means

Required dynamic route segments ([arg]) must match RouteRegex.ARG: a name starting with a letter or underscore followed by alphanumerics/underscores. Segments like [1id], [my-arg], or [] are rejected by verify_route_validity when the page is added.

Source

Thrown at reflex/route.py:54

                msg = f"Catchall pattern `{part}` must be at the end of the route."
                raise ValueError(msg)
            continue
        if part.startswith("[["):
            if constants.RouteRegex.OPTIONAL_ARG.fullmatch(part):
                continue
            msg = (
                f"Route part `{part}` with optional argument is not valid. "
                "Reflex only supports optional arguments that start with an alphabetic character or underscore, "
                "followed by alphanumeric characters or underscores."
            )
            raise ValueError(msg)
        if not constants.RouteRegex.ARG.fullmatch(part):
            msg = (
                f"Route part `{part}` with argument is not valid. "
                "Reflex only supports argument names that start with an alphabetic character or underscore, "
                "followed by alphanumeric characters or underscores."
            )
            raise ValueError(msg)


def get_route_args(route: str) -> dict[str, str]:
    """Get the dynamic arguments for the given route.

    Args:
        route: The route to get the arguments for.

    Returns:
        The route arguments.
    """
    args = {}

    def _add_route_arg(arg_name: str, type_: str):
        if arg_name in args:
            msg = (
                f"Arg name `{arg_name}` is used more than once in the route `{route}`."
            )

View on GitHub (pinned to 45b8ed5ab7)

Solutions

Use a valid Python-style identifier: [user_id] or [id]
Avoid hyphens, digits at the start, and empty brackets
Remember the arg name maps to a state var annotation, so it must be a valid identifier

Example fix

# before
app.add_page(page, route='/user/[user-id]')

# after
app.add_page(page, route='/user/[user_id]')

Defensive patterns

Strategy: validation

Validate before calling

import re
ARG = re.compile(r'\[[A-Za-z_][A-Za-z0-9_]*\]')

def valid_arg(part: str) -> bool:
    return bool(ARG.fullmatch(part))

Type guard

def is_valid_route_part(part: str) -> bool:
    import re
    return bool(re.fullmatch(r'\[[A-Za-z_][A-Za-z0-9_]*\]', part))

Prevention

Keep arg names valid Python identifiers since they map to state var annotations
Lint routes in CI with a regex test

When it happens

Trigger: app.add_page(page, route='/user/[user-id]') or '/post/[1id]' — invalid identifier characters inside single brackets.

Common situations: Translating kebab-case URL slugs into route params; using numeric IDs as param names; typos leaving empty brackets [].

Related errors

AI-assisted analysis of reflex-dev/reflex@45b8ed5ab7 (2026-08-28). Data as JSON: /api/errors/954429d625d415f1. Report an issue: GitHub.