pallets/flask · error · NoAppException

A valid Flask application was not obtained from '{module.__n

Error message

A valid Flask application was not obtained from '{module.__name__}:{app_name}'.

What it means

Raised at the end of `find_app_by_string` when the resolved attribute (or the factory's return value) is not an instance of `flask.Flask` (checked with `isinstance(app, Flask)`). Flask found something at the given name but it isn't a usable application object.

Source

Thrown at src/flask/cli.py:194

    if inspect.isfunction(attr):
        try:
            app = attr(*args, **kwargs)
        except TypeError as e:
            if not _called_with_wrong_args(attr):
                raise

            raise NoAppException(
                f"The factory {app_name!r} in module"
                f" {module.__name__!r} could not be called with the"
                " specified arguments."
            ) from e
    else:
        app = attr

    if isinstance(app, Flask):
        return app

    raise NoAppException(
        "A valid Flask application was not obtained from"
        f" '{module.__name__}:{app_name}'."
    )


def prepare_import(path: str) -> str:
    """Given a filename this will try to calculate the python path, add it
    to the search path and return the actual module name that is expected.
    """
    path = os.path.realpath(path)

    fname, ext = os.path.splitext(path)
    if ext == ".py":
        path = fname

    if os.path.basename(path) == "__init__":
        path = os.path.dirname(path)

View on GitHub ↗ (pinned to 6a2f545bfd)

Solutions

Ensure the factory ends with `return app` and that the named variable holds the Flask instance itself.
Wrap middleware on `app.wsgi_app` (`app.wsgi_app = ProxyFix(app.wsgi_app)`) instead of replacing the Flask object.
If the target is a callable class or partial rather than a plain function, wrap it in a `def` factory — Flask only auto-calls plain functions.
Check for duplicate/conflicting flask installations with `pip list` and `python -c 'import flask; print(flask.__file__)'`.

Example fix

# before
def create_app():
    app = Flask(__name__)
    ...  # no return
# after
def create_app():
    app = Flask(__name__)
    ...
    return app

Defensive patterns

Strategy: type-guard

Validate before calling

from flask import Flask
from myproject import create_app
assert isinstance(create_app(), Flask), "factory must return a Flask instance"

Type guard

from flask import Flask
def is_flask_app(obj):
    return isinstance(obj, Flask)

Try / catch

try:
    app = info.load_app()
except NoAppException as e:
    print(f"Spec did not yield a Flask app: {e}", file=sys.stderr)
    sys.exit(2)

Prevention

Make the factory return the Flask instance — a common bug is returning None after calling app.run() or building blueprints
Point the spec at the Flask object itself, not a blueprint, wsgi wrapper, or the module
Add a return-type annotation (-> Flask) and let mypy/pyright catch wrong returns

When it happens

Trigger: `--app` pointing at a factory that returns None (forgot the `return app`), a variable holding a Blueprint, a non-function callable class instance (only `inspect.isfunction` attrs get called, so a class or functools.partial named as the target is returned as-is and fails the isinstance check), or an app wrapped in WSGI middleware (`app = ProxyFix(app)`).

Common situations: Application factory missing its return statement; pointing at a Blueprint or an APIRouter-style object; wrapping the app in middleware and reassigning the same variable name; two Flask installs in different virtualenvs so isinstance fails across duplicate flask modules on a broken sys.path.

Related errors

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