pallets/flask · error · NoAppException

A valid Flask application was not obtained from

Error message

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

What it means

After resolving the attribute named in the --app/FLASK_APP string (either a plain attribute or the return value of a called factory), Flask checks isinstance(app, Flask). If the resolved object is not a Flask instance, it raises NoAppException stating no valid app was obtained from 'module:attribute'. The attribute was found and (if a function) called successfully, but it did not yield a Flask application object.

Solutions

Verify the named attribute is actually a Flask instance or a factory returning one: print(type(mymodule.app)).
Point --app at the correct attribute name that holds the Flask app.
If using a factory, ensure it returns app (return app) rather than a dict, None, or other object.

Example fix

# before
export FLASK_APP='mypkg:db_config'   # db_config is a dict

# after
export FLASK_APP='mypkg:app'         # app is a Flask instance

Defensive patterns

Strategy: type-guard

Validate before calling

from flask import Flask

def assert_flask_app(attr_path, obj):
    if not isinstance(obj, Flask):
        raise TypeError(f'{attr_path} resolved to {type(obj).__name__}, not a Flask app')
    return obj

Type guard

from flask import Flask
import typing as t

def is_flask_app(obj: t.Any) -> 't.TypeGuard[Flask]':
    return isinstance(obj, Flask)

Try / catch

from flask.cli import NoAppException
try:
    app = locate_app(module, name)
except NoAppException as e:
    if 'not obtained' in str(e):
        print(f'{module}:{name} is not a Flask instance; check the attribute name')
    raise

Prevention

Name the Flask instance consistently (e.g. always 'app') across modules.
Add an assertion at import time that the exported symbol is a Flask instance.

When it happens

Trigger: Pointing --app at a module:attribute where the attribute is a dict, a string, a non-Flask WSGI callable, or a function whose return value is not a Flask instance. For example the attribute holds a configuration dict, or a factory returns a plain dict/None instead of app.

Common situations: Naming the wrong attribute in FLASK_APP (e.g. 'mypkg:config' instead of 'mypkg:app'). A factory function that returns the wrong object after a refactor. Returning a blueprint or an app group instead of a single Flask app.

Related errors

AI-assisted analysis of pallets/flask@3596b1ab61 (2026-08-11). Data as JSON: /api/errors/c7b8e9b734375f93. Report an issue: GitHub.

Appendix: 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 3596b1ab61)