pallets/flask · error · NoAppException

Failed to parse {app_name!r} as an attribute name or functio

Error message

Failed to parse {app_name!r} as an attribute name or function call.

What it means

A `NoAppException` from `find_app_by_string`, which handles the part after the colon in `--app module:name`. Flask parses that string with `ast.parse(..., mode='eval')`; if it isn't valid Python for a single expression (SyntaxError), or parses to something other than a bare name or a function call (e.g. an attribute chain, subscript, or literal), Flask rejects it because it only supports `name` or `factory(literal_args)` forms.

Source

Thrown at src/flask/cli.py:131

        return True
    finally:
        # Delete tb to break a circular reference.
        # https://docs.python.org/2/library/sys.html#sys.exc_info
        del tb


def find_app_by_string(module: ModuleType, app_name: str) -> Flask:
    """Check if the given string is a variable name or a function. Call
    a function to get the app instance, or return the variable directly.
    """
    from . import Flask

    # Parse app_name as a single expression to determine if it's a valid
    # attribute name or function call.
    try:
        expr = ast.parse(app_name.strip(), mode="eval").body
    except SyntaxError:
        raise NoAppException(
            f"Failed to parse {app_name!r} as an attribute name or function call."
        ) from None

    if isinstance(expr, ast.Name):
        name = expr.id
        args = []
        kwargs = {}
    elif isinstance(expr, ast.Call):
        # Ensure the function name is an attribute name only.
        if not isinstance(expr.func, ast.Name):
            raise NoAppException(
                f"Function reference must be a simple name: {app_name!r}."
            )

        name = expr.func.id

        # Parse the positional and keyword arguments as literals.
        try:

View on GitHub ↗ (pinned to 6a2f545bfd)

Solutions

1. Quote the whole app string so the shell passes it intact: `flask --app 'myapp:create_app("dev")' run`.
2. Use only a simple name or call after the colon — dots belong before the colon (`pkg.module:app`, not `pkg:module.app`).
3. Check for balanced parentheses and valid Python literals in the factory-call form.

Example fix

# before
flask --app myapp:create_app(dev) run   # shell mangles parens; 'dev' not a literal

# after
flask --app 'myapp:create_app("dev")' run

import ast
app_name = 'create_app("prod")'
try:
    ast.parse(app_name.strip(), mode='eval')
except SyntaxError:
    raise SystemExit('invalid --app expression')

def is_valid_app_expr(s):
    import ast
    try:
        node = ast.parse(s.strip(), mode='eval').body
        return isinstance(node, (ast.Name, ast.Attribute, ast.Call))
    except SyntaxError:
        return False

When it happens

Trigger: `flask --app 'module:...'` where the part after the colon is malformed or unsupported: unbalanced parens (`create_app(`), an attribute access (`pkg.app` after the colon), a subscript (`apps[0]`), stray shell-quoting artifacts, or an empty/whitespace name.

Common situations: Shell quoting mistakes where the shell eats quotes or parentheses before Flask sees them (especially in Windows cmd vs PowerShell vs bash); using dotted attribute paths after the colon expecting import-string semantics like gunicorn's; typos leaving invalid syntax.

Related errors

• Failed to parse arguments as literal values: {app_name!r}.
• Detected multiple Flask applications in module '{module.__na
• Detected factory '{attr_name}' in module '{module.__name__}'
• Failed to find Flask application or factory in module '{modu
• Function reference must be a simple name: {app_name!r}.

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