pallets/flask · error · NoAppException

While importing {module_name!r}, an ImportError was raised:

Error message

While importing {module_name!r}, an ImportError was raised:

{traceback.format_exc()}

What it means

Raised in `locate_app` when importing the target module itself succeeded in being found but an ImportError was raised from code *inside* it (detected because the traceback has depth > 1, i.e. `tb_next` is set). Flask includes the full formatted traceback so you see the real failing import rather than blaming the app module name.

Source

Thrown at src/flask/cli.py:250

) -> Flask: ...


@t.overload
def locate_app(
    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:

View on GitHub ↗ (pinned to 6a2f545bfd)

Solutions

1. Read the embedded traceback — the last line names the actual module that failed to import — and install it (`pip install <package>`) into the same environment that runs `flask`.
2. Confirm you're in the right virtualenv: `which flask` and `which python` should point into the same env.
3. If the traceback shows a circular import, break the cycle by deferring one import into the function that uses it.

Example fix

# before (mymodule.py)
import pandas  # not installed
# after
pip install pandas   # in the venv that runs flask

python -c "import myproject"  # surfaces the real ImportError with full traceback before invoking flask

try:
    app = info.load_app()
except NoAppException as e:
    # message already embeds the inner traceback — log it whole
    logging.error("App import failed:\n%s", e)
    sys.exit(2)

When it happens

Trigger: `flask run` / `flask --app mymodule` where mymodule (or anything it imports at top level) does `import somepkg` for a package that isn't installed in the active environment, or has a circular import that surfaces as ImportError.

Common situations: Missing dependency after switching virtualenvs or fresh clones without `pip install -r requirements.txt`; a dependency renamed or dropped in an upgrade; circular imports introduced by moving code between modules; optional imports without try/except.

Related errors

• Failed to find attribute {name!r} in {module.__name__!r}.
• Could not import {module_name!r}.
• python-dotenv must be installed to load an env file.
• Using ad-hoc certificates requires the cryptography library.
• Install Flask with the 'async' extra in order to use async v

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