langflow-ai/langflow · error · RuntimeError

Direct-uvicorn startup (Windows/macOS) requires a pre-built

Error message

Direct-uvicorn startup (Windows/macOS) requires a pre-built FastAPI application.

What it means

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.

Source

Thrown at src/backend/base/langflow/__main__.py:532

        # LANGFLOW_GUNICORN_PRELOAD is a Gunicorn-only knob: it triggers fork-safe
        # master-process preload so workers inherit state via copy-on-write. On
        # the direct-uvicorn path there is no master/worker split and no fork,
        # so the env var is silently inert. Warn loudly so users diagnosing
        # "preload isn't doing anything on my Mac" don't have to read source.
        if os.environ.get("LANGFLOW_GUNICORN_PRELOAD", "false").lower() == "true":
            logger.warning(
                "LANGFLOW_GUNICORN_PRELOAD=true is ignored on %s: this platform "
                "uses single-process uvicorn (no fork), so master preload / "
                "copy-on-write inheritance does not apply.",
                platform.system(),
            )

        with progress.step(6):
            import uvicorn

            if app is None:
                msg = "Direct-uvicorn startup (Windows/macOS) requires a pre-built FastAPI application."
                raise RuntimeError(msg)

            # Print summary and banner before starting the server, since uvicorn is a blocking call.
            # We _may_ be able to subprocess, but with window's spawn behavior, we'd have to move all
            # non-picklable code to the subprocess.
            progress.print_summary()
            print_banner(str(host), int(port or 7860), protocol)

        from langflow.helpers.windows_postgres_helper import LANGFLOW_DATABASE_URL, POSTGRESQL_PREFIXES

        db_url = os.environ.get(LANGFLOW_DATABASE_URL, "")
        loop_type = "asyncio"
        if (
            platform.system() == "Windows"
            and db_url
            and any(db_url.startswith(prefix) for prefix in POSTGRESQL_PREFIXES)
        ):
            loop_type = "none"  # Preserve pre-configured WindowsSelectorEventLoopPolicy

View on GitHub (pinned to 976ec789d2)

Solutions

1. Pass a pre-built app: build the FastAPI app first (langflow.server.create_app or equivalent) and pass it as app=.
2. Or invoke the CLI normally ('langflow run') — it constructs the app on these platforms for you.
3. For factory-style startup on Unix, use the Linux path where gunicorn accepts the app factory instead.

Example fix

# before (macOS/Windows)
run(app=None, app_factory=app_factory)  # RuntimeError: Direct-uvicorn startup requires a pre-built FastAPI application
# after
app = app_factory()
run(app=app)

import platform
if platform.system() in ("Windows", "Darwin"):
    assert app is not None, "Build the FastAPI app before run() on Windows/macOS; on Linux pass app_factory instead",

When it happens

Trigger: 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.

Common situations: Internal/embedded usage of langflow.__main__'s run helper; code ported from a Linux gunicorn deployment to a dev machine on macOS/Windows.

Related errors

• Gunicorn startup requires an application factory.
• Refusing to start with {num_workers} workers and the default
• Settings service is already initialized. This indicates pote
• err
• class_name {class_name!r} is a Windows-reserved device name

AI-assisted analysis of langflow-ai/langflow@976ec789d2 (2026-08-14). Data as JSON: /api/errors/c2e811ccfce65676. Report an issue: GitHub.