{"record":{"id":"10cd6dcdaad75edb","repo":"reflex-dev/reflex","slug":"cannot-include-stylesheets-from-outside-the-assets","errorCode":null,"errorMessage":"Cannot include stylesheets from outside the assets directory: {stylesheet_full_path}","messagePattern":"Cannot include stylesheets from outside the assets directory: (.+?)","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"reflex/compiler/compiler.py","lineNumber":303,"sourceCode":"\ndef _validate_stylesheet(stylesheet_full_path: Path, assets_app_path: Path) -> None:\n    \"\"\"Validate the stylesheet.\n\n    Args:\n        stylesheet_full_path: The stylesheet to validate.\n        assets_app_path: The path to the assets directory.\n\n    Raises:\n        ValueError: If the stylesheet is not supported.\n        FileNotFoundError: If the stylesheet is not found.\n    \"\"\"\n    suffix = stylesheet_full_path.suffix[1:] if stylesheet_full_path.suffix else \"\"\n    if suffix not in constants.Reflex.STYLESHEETS_SUPPORTED:\n        msg = f\"Stylesheet file {stylesheet_full_path} is not supported.\"\n        raise ValueError(msg)\n    if not stylesheet_full_path.absolute().is_relative_to(assets_app_path.absolute()):\n        msg = f\"Cannot include stylesheets from outside the assets directory: {stylesheet_full_path}\"\n        raise FileNotFoundError(msg)\n    if not stylesheet_full_path.name:\n        msg = f\"Stylesheet file name cannot be empty: {stylesheet_full_path}\"\n        raise ValueError(msg)\n    if (\n        len(\n            stylesheet_full_path\n            .absolute()\n            .relative_to(assets_app_path.absolute())\n            .parts\n        )\n        == 1\n        and stylesheet_full_path.stem == PageNames.STYLESHEET_ROOT\n    ):\n        msg = f\"Stylesheet file name cannot be '{PageNames.STYLESHEET_ROOT}': {stylesheet_full_path}\"\n        raise ValueError(msg)\n\n\ndef _compile_root_stylesheet(","sourceCodeStart":285,"sourceCodeEnd":321,"githubUrl":"https://github.com/reflex-dev/reflex/blob/45b8ed5ab735f8a56bbb09a42384f030eb0208e7/reflex/compiler/compiler.py#L285-L321","documentation":"When compiling the root stylesheet, Reflex refuses any local stylesheet whose absolute path is not inside the app's assets directory. Styles are concatenated into a single root stylesheet, so they must live under .web/assets (or wherever Dirs.APP_ASSETS points) to be found at build time.","triggerScenarios":"Passing an absolute or ../-escaping path in add_styles, e.g. rx.App(add_styles=[str(project_root / \"../shared/style.css\")]) or \"/absolute/path/style.css\" outside assets. Any non-URL stylesheet is joined onto assets_app_path and checked with is_relative_to.","commonSituations":"Monorepo setups where shared styles sit outside the Reflex app directory; generated absolute paths baked into config; moving the assets directory while keeping old absolute references.","solutions":["Copy or symlink the stylesheet into your app's assets directory and reference it as \"/style.css\"","For styles outside the app, load them via a <link> URL (rx.el.link or a hosted URL in add_styles) instead of a local path","Restructure so shared styles ship as a package asset referenced with @pkg: syntax"],"exampleFix":"# before\napp = rx.App(add_styles=[\"/home/user/project/shared/style.css\"])\n# after\napp = rx.App(add_styles=[\"/style.css\"])  # file moved into <project>/assets/","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef validate_local_stylesheet(p: str, assets_dir: Path) -> None:\n    if p.startswith((\"http://\", \"https://\")):\n        return\n    full = (assets_dir / p.lstrip(\"/\")).resolve()\n    if not full.is_relative_to(assets_dir.resolve()):\n        raise ValueError(f\"stylesheet escapes assets dir: {p}\")","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always reference local styles as assets-rooted relative paths like /css/theme.css","Never build absolute filesystem paths into add_styles","Keep shared styles inside the app assets dir or serve them via URL"],"tags":["reflex","stylesheets","path-validation","compilation"],"backgroundTag":"path-outside-allowed-directory","analyzedSha":"45b8ed5ab735f8a56bbb09a42384f030eb0208e7","analyzedAt":"2026-08-28T19:25:27.644Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}