pallets/flask · error · NoAppException

Could not import .

Error message

Could not import {module_name!r}.

What it means

In locate_app(), __import__(module_name) raised ImportError with a traceback depth of 1 (no tb_next), meaning the module itself could not be found on sys.path, and raise_if_not_found is True. Flask reports that the top-level module name is not importable.

Solutions

1. Confirm the module name is spelled correctly and is importable: python -c 'import module_name'.
2. Run flask from the project root where the module is on sys.path, or use a dotted path (pkg.subpkg.module).
3. If pointing at a file, ensure prepare_import converted it to a valid module name.

Example fix

# before
export FLASK_APP='myapp'   # no module named 'myapp' from cwd

# after
cd /path/to/project
export FLASK_APP='mypkg.app'

import importlib.util

def module_resolves(module_name: str) -> bool:
    return importlib.util.find_spec(module_name) is not None

null

import importlib
try:
    importlib.import_module(module_name)
except ModuleNotFoundError:
    print(f'{module_name} not found on sys.path; check spelling and cwd')
    raise

When it happens

Trigger: Setting FLASK_APP or --app to a module name that does not exist (typo), running flask from the wrong working directory so the module is not on sys.path, or pointing at a file whose prepared module name does not resolve. Distinct from error 22 because here the import failure is at the top level, not inside the module body.

Common situations: cd into the wrong folder and run flask; the package isn't importable. FLASK_APP points to a module that was renamed or deleted. The module lives in a package and only the bare name was given.

Related errors

• A valid Flask application was not obtained from
• Could not locate a Flask application. Use the 'flask --app'…
• The factory in module could not be called with the…
• While importing , an ImportError was raised:\n\n
• Allowed methods must be a list of strings, for example…

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

Appendix: source

Thrown at src/flask/cli.py:255

    module_name: str, app_name: str | None, raise_if_not_found: t.Literal[False] = ...
) -> Flask | None: ...


def locate_app(
    module_name: str, app_name: str | None, raise_if_not_found: bool = True
) -> Flask | None:
    try:
        __import__(module_name)
    except ImportError:
        # Reraise the ImportError if it occurred within the imported module.
        # Determine this by checking whether the trace has a depth > 1.
        if sys.exc_info()[2].tb_next:  # type: ignore[union-attr]
            raise NoAppException(
                f"While importing {module_name!r}, an ImportError was"
                f" raised:\n\n{traceback.format_exc()}"
            ) from None
        elif raise_if_not_found:
            raise NoAppException(f"Could not import {module_name!r}.") from None
        else:
            return None

    module = sys.modules[module_name]

    if app_name is None:
        return find_best_app(module)
    else:
        return find_app_by_string(module, app_name)


def get_version(ctx: click.Context, param: click.Parameter, value: t.Any) -> None:
    if not value or ctx.resilient_parsing:
        return

    flask_version = importlib.metadata.version("flask")
    werkzeug_version = importlib.metadata.version("werkzeug")

View on GitHub (pinned to 3596b1ab61)