{"record":{"id":"1bb626db65b1ee38","repo":"langflow-ai/langflow","slug":"gunicorn-startup-requires-an-application-factory","errorCode":null,"errorMessage":"Gunicorn startup requires an application factory.","messagePattern":"Gunicorn startup requires an application factory\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"src/backend/base/langflow/__main__.py","lineNumber":571,"sourceCode":"            **build_direct_uvicorn_kwargs(\n                host=host,\n                port=port,\n                log_level=log_level,\n                workers=get_number_of_workers(workers),\n                loop=loop_type,\n                ssl_cert_file_path=ssl_cert_file_path,\n                ssl_key_file_path=ssl_key_file_path,\n                trust_proxy=get_settings_service().settings.rate_limit_trust_proxy,\n            ),\n        )\n    else:\n        with progress.step(6):\n            # Use Gunicorn with LangflowUvicornWorker for non-Windows systems\n            from langflow.server import LangflowApplication\n\n            if app_factory is None:\n                msg = \"Gunicorn startup requires an application factory.\"\n                raise RuntimeError(msg)\n\n            num_workers = get_number_of_workers(workers)\n            ensure_multi_worker_safe(num_workers)\n            options = {\n                \"bind\": f\"{host}:{port}\",\n                \"workers\": num_workers,\n                \"timeout\": worker_timeout,\n                \"certfile\": ssl_cert_file_path,\n                \"keyfile\": ssl_key_file_path,\n                \"log_level\": log_level.lower() if log_level is not None else \"info\",\n                \"preload_app\": os.environ.get(\"LANGFLOW_GUNICORN_PRELOAD\", \"false\").lower() == \"true\",\n            }\n            server = LangflowApplication(app_factory, options)\n\n            # Start the webapp process\n            process_manager.webapp_process = Process(target=server.run)\n            process_manager.webapp_process.start()\n","sourceCodeStart":553,"sourceCodeEnd":589,"githubUrl":"https://github.com/langflow-ai/langflow/blob/976ec789d2886a86de109c044d089d68e96c9a35/src/backend/base/langflow/__main__.py#L553-L589","documentation":"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.","triggerScenarios":"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.","commonSituations":"Embedded launches that construct the app eagerly and skip the factory; code copied from the Windows/macOS single-process path being run on Linux.","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."],"exampleFix":"# before (Linux)\nrun(app=app, app_factory=None)  # RuntimeError: Gunicorn startup requires an application factory\n# after\nrun(app=None, app_factory=create_app)","handlingStrategy":"validation","validationCode":"import platform\nimport collections.abc as abc\nif platform.system() not in (\"Windows\", \"Darwin\"):\n    assert app_factory is not None and callable(app_factory), \"gunicorn path needs a callable app factory\"","typeGuard":"def is_app_factory(obj) -> bool:\n    return callable(obj) and not hasattr(obj, \"routes\")  # factory: callable without FastAPI attrs","tryCatchPattern":null,"preventionTips":["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)."],"tags":["startup","gunicorn","platform","linux","app-factory"],"backgroundTag":null,"analyzedSha":"976ec789d2886a86de109c044d089d68e96c9a35","analyzedAt":"2026-08-14T18:23:12.227Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}