What causes "Gunicorn startup requires an application factory." in langflow-ai/langflow?

Pass the application factory (a zero-arg callable returning the FastAPI app) as app_factory= on Unix.

langflow-ai/langflow · error · RuntimeError

Gunicorn startup requires an application factory.

Error message

Gunicorn startup requires an application factory.

What it means

On non-Windows platforms langflow starts under gunicorn with LangflowUvicornWorker, and gunicorn needs an application factory to call in each worker. If the internal run path reaches the gunicorn branch with app_factory=None, it raises RuntimeError immediately. The caller must supply the factory; a pre-built app object alone is not usable here.

Source

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

            **build_direct_uvicorn_kwargs(
                host=host,
                port=port,
                log_level=log_level,
                workers=get_number_of_workers(workers),
                loop=loop_type,
                ssl_cert_file_path=ssl_cert_file_path,
                ssl_key_file_path=ssl_key_file_path,
                trust_proxy=get_settings_service().settings.rate_limit_trust_proxy,
            ),
        )
    else:
        with progress.step(6):
            # Use Gunicorn with LangflowUvicornWorker for non-Windows systems
            from langflow.server import LangflowApplication

            if app_factory is None:
                msg = "Gunicorn startup requires an application factory."
                raise RuntimeError(msg)

            num_workers = get_number_of_workers(workers)
            ensure_multi_worker_safe(num_workers)
            options = {
                "bind": f"{host}:{port}",
                "workers": num_workers,
                "timeout": worker_timeout,
                "certfile": ssl_cert_file_path,
                "keyfile": ssl_key_file_path,
                "log_level": log_level.lower() if log_level is not None else "info",
                "preload_app": os.environ.get("LANGFLOW_GUNICORN_PRELOAD", "false").lower() == "true",
            }
            server = LangflowApplication(app_factory, options)

            # Start the webapp process
            process_manager.webapp_process = Process(target=server.run)
            process_manager.webapp_process.start()

View on GitHub (pinned to 976ec789d2)

Solutions

Pass the application factory (a zero-arg callable returning the FastAPI app) as app_factory= on Unix.
Or use the standard CLI ('langflow run'), which wires the factory itself.
For single-process uvicorn-style startup on a dev box, use the platform-appropriate branch rather than forcing gunicorn.

Example fix

# before (Linux)
run(app=app, app_factory=None)  # RuntimeError: Gunicorn startup requires an application factory
# after
run(app=None, app_factory=create_app)

Defensive patterns

Strategy: validation

Validate before calling

import platform
import collections.abc as abc
if platform.system() not in ("Windows", "Darwin"):
    assert app_factory is not None and callable(app_factory), "gunicorn path needs a callable app factory"

Type guard

def is_app_factory(obj) -> bool:
    return callable(obj) and not hasattr(obj, "routes")  # factory: callable without FastAPI attrs

Prevention

On Unix always hand the run helper a zero-arg factory, not a built app.
Reuse langflow's own app factory rather than rolling your own.
Test launchers on both platform families (uvicorn branch and gunicorn branch).

When it happens

Trigger: Programmatically calling langflow.__main__'s run helper on Linux with app set but app_factory=None; a custom launcher that only built the app object.

Common situations: Embedded launches that construct the app eagerly and skip the factory; code copied from the Windows/macOS single-process path being run on Linux.

Related errors

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