pallets/flask · error · NoAppException

Detected multiple Flask applications in module '{module.__na

Error message

Detected multiple Flask applications in module '{module.__name__}'. Use '{module.__name__}:name' to specify the correct one.

What it means

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.

Source

Thrown at src/flask/cli.py:60

    """Given a module instance this tries to find the best possible
    application in the module or raises an exception.
    """
    from . import Flask

    # Search for the most common names first.
    for attr_name in ("app", "application"):
        app = getattr(module, attr_name, None)

        if isinstance(app, Flask):
            return app

    # Otherwise find the only object that is a Flask instance.
    matches = [v for v in module.__dict__.values() if isinstance(v, Flask)]

    if len(matches) == 1:
        return matches[0]
    elif len(matches) > 1:
        raise NoAppException(
            "Detected multiple Flask applications in module"
            f" '{module.__name__}'. Use '{module.__name__}:name'"
            " to specify the correct one."
        )

    # Search for app factory functions.
    for attr_name in ("create_app", "make_app"):
        app_factory = getattr(module, attr_name, None)

        if inspect.isfunction(app_factory):
            try:
                app = app_factory()

                if isinstance(app, Flask):
                    return app
            except TypeError as e:
                if not _called_with_wrong_args(app_factory):
                    raise

View on GitHub ↗ (pinned to 6a2f545bfd)

Solutions

1. Specify the instance explicitly: `flask --app 'module:name' run` (or `FLASK_APP=module:name`).
2. Rename the intended instance to `app` (or `application`) — the named-attribute check runs before the ambiguity scan and wins.
3. Avoid importing other Flask instances into the entry module's global namespace (import inside functions, or alias behind a non-module-level scope).

Example fix

# before
flask --app wsgi run
# Error: Detected multiple Flask applications in module 'wsgi'...

# after
flask --app 'wsgi:public_app' run

# shell check before running the CLI
# grep -cE '^\s*\w+\s*=\s*Flask\(' app.py  → if >1, use explicit name

When it happens

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

Common situations: 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.

Related errors

• Failed to find Flask application or factory in module '{modu
• Could not locate a Flask application. Use the 'flask --app'
• Detected factory '{attr_name}' in module '{module.__name__}'
• Failed to parse {app_name!r} as an attribute name or functio
• Failed to parse arguments as literal values: {app_name!r}.

AI-assisted analysis of pallets/flask@6a2f545bfd (2026-07-31). Data as JSON: /data/errors/f2c3c2b6f8f9a1aa.json. Report an issue: GitHub ↗.