{"record":{"id":"c2e811ccfce65676","repo":"langflow-ai/langflow","slug":"direct-uvicorn-startup-windows-macos-requires-a","errorCode":null,"errorMessage":"Direct-uvicorn startup (Windows/macOS) requires a pre-built FastAPI application.","messagePattern":"Direct-uvicorn startup \\(Windows/macOS\\) requires a pre-built FastAPI application\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/backend/base/langflow/__main__.py","lineNumber":532,"sourceCode":"        # LANGFLOW_GUNICORN_PRELOAD is a Gunicorn-only knob: it triggers fork-safe\n        # master-process preload so workers inherit state via copy-on-write. On\n        # the direct-uvicorn path there is no master/worker split and no fork,\n        # so the env var is silently inert. Warn loudly so users diagnosing\n        # \"preload isn't doing anything on my Mac\" don't have to read source.\n        if os.environ.get(\"LANGFLOW_GUNICORN_PRELOAD\", \"false\").lower() == \"true\":\n            logger.warning(\n                \"LANGFLOW_GUNICORN_PRELOAD=true is ignored on %s: this platform \"\n                \"uses single-process uvicorn (no fork), so master preload / \"\n                \"copy-on-write inheritance does not apply.\",\n                platform.system(),\n            )\n\n        with progress.step(6):\n            import uvicorn\n\n            if app is None:\n                msg = \"Direct-uvicorn startup (Windows/macOS) requires a pre-built FastAPI application.\"\n                raise RuntimeError(msg)\n\n            # Print summary and banner before starting the server, since uvicorn is a blocking call.\n            # We _may_ be able to subprocess, but with window's spawn behavior, we'd have to move all\n            # non-picklable code to the subprocess.\n            progress.print_summary()\n            print_banner(str(host), int(port or 7860), protocol)\n\n        from langflow.helpers.windows_postgres_helper import LANGFLOW_DATABASE_URL, POSTGRESQL_PREFIXES\n\n        db_url = os.environ.get(LANGFLOW_DATABASE_URL, \"\")\n        loop_type = \"asyncio\"\n        if (\n            platform.system() == \"Windows\"\n            and db_url\n            and any(db_url.startswith(prefix) for prefix in POSTGRESQL_PREFIXES)\n        ):\n            loop_type = \"none\"  # Preserve pre-configured WindowsSelectorEventLoopPolicy\n","sourceCodeStart":514,"sourceCodeEnd":550,"githubUrl":"https://github.com/langflow-ai/langflow/blob/976ec789d2886a86de109c044d089d68e96c9a35/src/backend/base/langflow/__main__.py#L514-L550","documentation":"On Windows/macOS the server starts as a single-process uvicorn, so the CLI requires a pre-built FastAPI application object to hand to uvicorn.run(); there is no gunicorn arbiter to call a factory after fork. If the caller reaches the uvicorn branch with app=None (only a factory supplied), startup raises RuntimeError. The caller of this internal run function must pass app on these platforms.","triggerScenarios":"Programmatically invoking langflow's internal run function on Windows or macOS with app_factory set but app=None; custom launchers that assumed factory-mode works on every platform.","commonSituations":"Internal/embedded usage of langflow.__main__'s run helper; code ported from a Linux gunicorn deployment to a dev machine on macOS/Windows.","solutions":["Pass a pre-built app: build the FastAPI app first (langflow.server.create_app or equivalent) and pass it as app=.","Or invoke the CLI normally ('langflow run') — it constructs the app on these platforms for you.","For factory-style startup on Unix, use the Linux path where gunicorn accepts the app factory instead."],"exampleFix":"# before (macOS/Windows)\nrun(app=None, app_factory=app_factory)  # RuntimeError: Direct-uvicorn startup requires a pre-built FastAPI application\n# after\napp = app_factory()\nrun(app=app)","handlingStrategy":"validation","validationCode":"import platform\nif platform.system() in (\"Windows\", \"Darwin\"):\n    assert app is not None, \"Build the FastAPI app before run() on Windows/macOS; on Linux pass app_factory instead\",","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Branch on platform.system() before choosing app vs app_factory.","Prefer the standard 'langflow run' CLI over embedding the internal run function.","Write platform-agnostic launchers that can supply both app and factory."],"tags":["startup","uvicorn","platform","windows","macos"],"backgroundTag":null,"analyzedSha":"976ec789d2886a86de109c044d089d68e96c9a35","analyzedAt":"2026-08-14T18:23:12.227Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}