{"id":"f2c3c2b6f8f9a1aa","repo":"pallets/flask","slug":"detected-multiple-flask-applications-in-module-m","errorCode":null,"errorMessage":"Detected multiple Flask applications in module '{module.__name__}'. Use '{module.__name__}:name' to specify the correct one.","messagePattern":"Detected multiple Flask applications in module '(.+?)'\\. Use '(.+?):name' to specify the correct one\\.","errorType":"exception","errorClass":"NoAppException","httpStatus":null,"severity":"error","filePath":"src/flask/cli.py","lineNumber":60,"sourceCode":"    \"\"\"Given a module instance this tries to find the best possible\n    application in the module or raises an exception.\n    \"\"\"\n    from . import Flask\n\n    # Search for the most common names first.\n    for attr_name in (\"app\", \"application\"):\n        app = getattr(module, attr_name, None)\n\n        if isinstance(app, Flask):\n            return app\n\n    # Otherwise find the only object that is a Flask instance.\n    matches = [v for v in module.__dict__.values() if isinstance(v, Flask)]\n\n    if len(matches) == 1:\n        return matches[0]\n    elif len(matches) > 1:\n        raise NoAppException(\n            \"Detected multiple Flask applications in module\"\n            f\" '{module.__name__}'. Use '{module.__name__}:name'\"\n            \" to specify the correct one.\"\n        )\n\n    # Search for app factory functions.\n    for attr_name in (\"create_app\", \"make_app\"):\n        app_factory = getattr(module, attr_name, None)\n\n        if inspect.isfunction(app_factory):\n            try:\n                app = app_factory()\n\n                if isinstance(app, Flask):\n                    return app\n            except TypeError as e:\n                if not _called_with_wrong_args(app_factory):\n                    raise","sourceCodeStart":42,"sourceCodeEnd":78,"githubUrl":"https://github.com/pallets/flask/blob/6a2f545bfd8ed31e19066a299296917e034aca58/src/flask/cli.py#L42-L78","documentation":"A `NoAppException` (a click.UsageError) from `find_best_app` in Flask's CLI app discovery. When `flask run`/`flask shell` imports the target module, it first looks for attributes named `app` or `application`; failing that, it scans the module namespace for Flask instances. If it finds more than one Flask object and none is named `app`/`application`, it cannot guess which to serve and refuses.","triggerScenarios":"Running `flask --app module run` (or with FLASK_APP=module) against a module whose globals contain two or more Flask instances — e.g. `from other_service import app as other_app` plus a locally created instance, or test/utility modules constructing multiple apps at import time.","commonSituations":"Importing another Flask app into the entry module for composition (DispatcherMiddleware setups); wsgi.py files that build both a debug and a prod app; renaming the main instance so neither `app` nor `application` matches while a second imported instance still exists.","solutions":["Specify the instance explicitly: `flask --app 'module:name' run` (or `FLASK_APP=module:name`).","Rename the intended instance to `app` (or `application`) — the named-attribute check runs before the ambiguity scan and wins.","Avoid importing other Flask instances into the entry module's global namespace (import inside functions, or alias behind a non-module-level scope)."],"exampleFix":"# before\nflask --app wsgi run\n# Error: Detected multiple Flask applications in module 'wsgi'...\n\n# after\nflask --app 'wsgi:public_app' run","handlingStrategy":"validation","validationCode":"# shell check before running the CLI\n# grep -cE '^\\s*\\w+\\s*=\\s*Flask\\(' app.py  → if >1, use explicit name","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Set FLASK_APP=module:app (or use --app module:app) explicitly instead of relying on auto-detection","Keep exactly one module-level Flask instance per module; put secondary apps in a factory or separate module","In app factories, avoid creating extra module-level Flask() instances for testing at import time"],"tags":["flask","cli","app-discovery","configuration"],"analyzedSha":"6a2f545bfd8ed31e19066a299296917e034aca58","analyzedAt":"2026-07-31T19:13:49.921Z","schemaVersion":2}