{"id":"86e6697915ea9fe5","repo":"tiangolo/fastapi","slug":"frontend-directory-directory-does-not-exist-r","errorCode":null,"errorMessage":"Frontend directory '{directory}' does not exist. Resolved absolute path: '{resolved_absolute_path}'","messagePattern":"Frontend directory '(.+?)' does not exist\\. Resolved absolute path: '(.+?)'","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"fastapi/routing.py","lineNumber":1909,"sourceCode":"        warnings.warn(\n            f\"Frontend directory '{directory}' does not exist. \"\n            f\"Resolved absolute path: '{_get_resolved_absolute_path(directory)}'\",\n            stacklevel=3,\n        )\n    return False\n\n\nclass _FrontendStaticFiles(StaticFiles):\n    def __init__(\n        self,\n        *,\n        directory: str | os.PathLike[str],\n        fallback: Literal[\"auto\", \"index.html\", \"404.html\"] | None,\n        check_dir: bool,\n    ) -> None:\n        self.fallback = fallback\n        if check_dir and not os.path.isdir(directory):\n            raise RuntimeError(\n                f\"Frontend directory '{directory}' does not exist. \"\n                f\"Resolved absolute path: '{_get_resolved_absolute_path(directory)}'\"\n            )\n        super().__init__(\n            directory=directory,\n            html=True,\n            check_dir=check_dir,\n            follow_symlink=False,\n        )\n        if check_dir and fallback in {\"index.html\", \"404.html\"}:\n            self._check_fallback_file(fallback)\n\n    def _check_fallback_file(self, fallback: str) -> None:\n        _, stat_result = self.lookup_path(fallback)\n        if stat_result is None or not stat.S_ISREG(stat_result.st_mode):\n            raise RuntimeError(\n                f\"Frontend fallback file '{fallback}' does not exist in \"\n                f\"directory '{self.directory}'. Resolved absolute directory: \"","sourceCodeStart":1891,"sourceCodeEnd":1927,"githubUrl":"https://github.com/tiangolo/fastapi/blob/42a41db11f6882807ac3c057b942178d53b97438/fastapi/routing.py#L1891-L1927","documentation":"`_FrontendStaticFiles.__init__` (routing.py:1908-1912) raises `RuntimeError` when `check_dir` is true and `os.path.isdir(directory)` is false. `check_dir` is resolved by `_resolve_frontend_check_dir` (routing.py:1881-1896): it is `True` unless `check_dir=\"auto\"` AND `FASTAPI_ENV == \"development\"`. So in normal/prod runs a missing frontend directory aborts app startup; under `fastapi dev` (FASTAPI_ENV=development) it is only a warning.","triggerScenarios":"`app.frontend(\"/\", directory=\"dist\")` where `dist/` does not exist on the working directory at startup, run without `FASTAPI_ENV=development`. Same with an absolute path that points nowhere, or a path relative to the wrong cwd.","commonSituations":"Running `uvicorn app.main:app` before building the frontend (`npm run build`); deploying with a relative `dist` path while the process cwd differs; CI running the app without the build artifact stage; mis-capitalized directory name.","solutions":["Build the frontend before starting the app so the directory exists.","Pass an absolute path resolved from the project root, e.g. `Path(__file__).resolve().parent.parent / \"dist\"`.","During local dev use `fastapi dev` (sets FASTAPI_ENV=development) or set `FASTAPI_ENV=development` to downgrade the failure to a warning.","Set `check_dir=False` only if you intentionally create the directory later at runtime."],"exampleFix":"# before\napp.frontend(\"/\", directory=\"dist\")  # dist/ missing in prod\n\n# after\nfrom pathlib import Path\nDIST = Path(__file__).resolve().parent.parent / \"dist\"\napp.frontend(\"/\", directory=str(DIST))","handlingStrategy":"validation","validationCode":"import os\nfrom pathlib import Path\n\ndef resolve_frontend_dir(directory: str | os.PathLike[str]) -> str:\n    resolved = Path(directory).resolve()\n    if not resolved.is_dir():\n        raise FileNotFoundError(\n            f\"Frontend directory '{directory}' missing (resolved: {resolved}). \"\n            f\"Build the frontend first.\"\n        )\n    return str(resolved)\n\n# usage\ndist = resolve_frontend_dir(os.getenv(\"FRONTEND_DIR\", \"dist\"))\napp.frontend(\"/\", directory=dist)","typeGuard":"import os\n\ndef frontend_dir_exists(directory: object) -> bool:\n    return isinstance(directory, (str, os.PathLike)) and os.path.isdir(directory)","tryCatchPattern":"# Construction-time failure: catch at app bootstrap to give a clear message.\ntry:\n    app.frontend(\"/\", directory=dist)\nexcept RuntimeError as exc:\n    raise SystemExit(f\"Startup aborted: {exc}. Run the frontend build first.\") from exc","preventionTips":["Resolve directory to an absolute path from the project root, not from cwd.","Build the frontend in CI/Docker before the app stage.","Use `fastapi dev` locally so a missing dir is a warning, not a hard failure."],"tags":["frontend","static-files","filesystem","configuration"],"analyzedSha":"42a41db11f6882807ac3c057b942178d53b97438","analyzedAt":"2026-08-04T19:23:32.007Z","schemaVersion":2}