reflex-dev/reflex · error · ValueError

Stylesheet file name cannot be '{PageNames.STYLESHEET_ROOT}'

Error message

Stylesheet file name cannot be '{PageNames.STYLESHEET_ROOT}': {stylesheet_full_path}

What it means

The root stylesheet is compiled to a file named styles.css (PageNames.STYLESHEET_ROOT). A user stylesheet with the same stem at the top level of assets would collide with / overwrite the generated root stylesheet, so Reflex rejects it.

Source

Thrown at reflex/compiler/compiler.py:318

        raise ValueError(msg)
    if not stylesheet_full_path.absolute().is_relative_to(assets_app_path.absolute()):
        msg = f"Cannot include stylesheets from outside the assets directory: {stylesheet_full_path}"
        raise FileNotFoundError(msg)
    if not stylesheet_full_path.name:
        msg = f"Stylesheet file name cannot be empty: {stylesheet_full_path}"
        raise ValueError(msg)
    if (
        len(
            stylesheet_full_path
            .absolute()
            .relative_to(assets_app_path.absolute())
            .parts
        )
        == 1
        and stylesheet_full_path.stem == PageNames.STYLESHEET_ROOT
    ):
        msg = f"Stylesheet file name cannot be '{PageNames.STYLESHEET_ROOT}': {stylesheet_full_path}"
        raise ValueError(msg)


def _compile_root_stylesheet(
    stylesheets: list[str],
    reset_style: bool = True,
    plugins: Sequence[Plugin] | None = None,
) -> str:
    """Compile the root stylesheet.

    Args:
        stylesheets: The stylesheets to include in the root stylesheet.
        reset_style: Whether to include CSS reset for margin and padding.
        plugins: The effective plugins for the active compile.

    Returns:
        The compiled root stylesheet.

    Raises:

View on GitHub (pinned to 45b8ed5ab7)

Solutions

1. Rename your file (e.g. global.css or theme.css) and update add_styles
2. Alternatively place it in a subdirectory (e.g. /styles/styles.css) — though renaming is cleaner
3. Remove the manual entry if the styles are already covered by the compiled root stylesheet

Example fix

# before
app = rx.App(add_styles=["/styles.css"])
# after
app = rx.App(add_styles=["/global.css"])  # after renaming assets/styles.css

from pathlib import Path

FORBIDDEN = "styles"
add_styles = [s for s in style_list
              if Path(s).stem != FORBIDDEN or len(Path(s).parts) > 2]

When it happens

Trigger: Having a file named styles.css (same stem) directly in the assets root and referencing it via rx.App(add_styles=["/styles.css"]). The check fires only when the path is exactly one part under assets_app_path and its stem equals styles.

Common situations: Naming your global CSS file styles.css and importing it manually in add_styles while it would already be handled/overwritten by the compiled root stylesheet; following generic CSS tutorials that suggest styles.css.

Related errors

• Stylesheet file {stylesheet_full_path} is not supported.
• Cannot include stylesheets from outside the assets directory
• The stylesheet file {stylesheet_full_path} does not exist.
• Event handler {self.fn.__name__} argument {clash!r} conflict
• Stylesheet file name cannot be empty: {stylesheet_full_path}

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