The Fix
Upgrade to version 2.0.0 or later.
Based on closed pallets/flask issue #2741 · PR/commit linked
Production note: Most teams hit this during upgrades or environment changes. Roll out with a canary and smoke critical endpoints (health, OpenAPI/docs) before 100%.
@@ -12,6 +12,8 @@ Unreleased
was not portable outside the ``flask`` command. Use
``click.get_current_context().obj`` if it's needed. :issue:`3552`
+- The CLI shows better error messages when the app failed to load
+ when looking up commands. :issue:`2741`
- Add :meth:`sessions.SessionInterface.get_cookie_name` to allow
repro.py
# there is no FLASK_APP env var
$ flask --help Sat 28 Apr 2018 01:25:50 PM -03
Traceback (most recent call last):
File "~Projects/personal/flasgger/venv/lib/python3.6/site-packages/flask/cli.py", line 235, in locate_app
__import__(module_name)
ModuleNotFoundError: No module named 'app'
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "~/Projects/personal/flasgger/venv/lib/python3.6/site-packages/flask/cli.py", line 529, in list_commands
rv.update(info.load_app().cli.list_commands(ctx))
File "~/Projects/personal/flasgger/venv/lib/python3.6/site-packages/flask/cli.py", line 372, in load_app
app = locate_app(self, import_name, name)
File "~/Projects/personal/flasgger/venv/lib/python3.6/site-packages/flask/cli.py", line 246, in locate_app
'Could not import "{name}".'.format(name=module_name)
flask.cli.NoAppException: Could not import "app".
Usage: flask [OPTIONS] COMMAND [ARGS]...
A general utility script for Flask applications.
Provides commands from Flask, extensions, and the application. Loads the
application defined in the FLASK_APP environment variable, or from a
wsgi.py file. Setting the FLASK_ENV environment variable to 'development'
will enable debug mode.
$ export FLASK_APP=hello.py
$ export FLASK_ENV=development
$ flask run
Options:
--version Show the flask version
--help Show this message and exit.
Commands:
routes Show the routes for the app.
run Runs a development server.
shell Runs a shell in the app context.
verify
Re-run: flask --help Sat 28 Apr 2018 01:25:50 PM -03
fix.md
Option A — Upgrade to fixed release\nUpgrade to version 2.0.0 or later.\nWhen NOT to use: This fix is not applicable if the application requires detailed tracebacks for debugging.\n\n
Why This Fix Works in Production
- Trigger: # there is no FLASK_APP env var
- Mechanism: The CLI did not provide user-friendly error messages when the app failed to load due to missing environment variables
- Why the fix works: Improves error messages when the Flask CLI cannot load the app by showing only the error message instead of a full traceback for specific cases. (first fixed release: 2.0.0).
Production impact:
- If left unfixed, the same config can fail only in production (env differences), causing startup failures or partial feature outages.
Why This Breaks in Prod
- Shows up under Python 3.6 in real deployments (not just unit tests).
- The CLI did not provide user-friendly error messages when the app failed to load due to missing environment variables
- Surfaces as: # there is no FLASK_APP env var
Proof / Evidence
- GitHub issue: #2741
- Fix PR: https://github.com/pallets/flask/pull/3711
- First fixed release: 2.0.0
- Reproduced locally: No (not executed)
- Last verified: 2026-02-09
- Confidence: 0.95
- Did this fix it?: Yes (upstream fix exists)
- Own content ratio: 0.23
Discussion
High-signal excerpts from the issue thread (symptoms, repros, edge-cases).
“Looks better in flask 1.0.2, so maybe we can close this? - with a help option - without any options:”
“* I can implement that and send a PR, just want to know if the idea is acceptable”
“Anything that improves help messages is great.”
“Please keep discussions in English, we can't support other languages.”
Failure Signature (Search String)
- # there is no FLASK_APP env var
Error Message
Stack trace
error.txt
Error Message
-------------
# there is no FLASK_APP env var
$ flask --help Sat 28 Apr 2018 01:25:50 PM -03
Traceback (most recent call last):
File "~Projects/personal/flasgger/venv/lib/python3.6/site-packages/flask/cli.py", line 235, in locate_app
__import__(module_name)
ModuleNotFoundError: No module named 'app'
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "~/Projects/personal/flasgger/venv/lib/python3.6/site-packages/flask/cli.py", line 529, in list_commands
rv.update(info.load_app().cli.list_commands(ctx))
File "~/Projects/personal/flasgger/venv/lib/python3.6/site-packages/flask/cli.py", line 372, in load_app
app = locate_app(self, import_name, name)
File "~/Projects/personal/flasgger/venv/lib/python3.6/site-packages/flask/cli.py", line 246, in locate_app
'Could not import "{name}".'.format(name=module_name)
flask.cli.NoAppException: Could not import "app".
Usage: flask [OPTIONS] COMMAND [ARGS]...
A general utility script for Flask applications.
Provides commands from Flask, extensions, and the application. Loads the
application defined in the FLASK_APP environment variable, or from a
wsgi.py file. Setting the FLASK_ENV environment variable to 'development'
will enable debug mode.
$ export FLASK_APP=hello.py
$ export FLASK_ENV=develo
... (truncated) ...
Stack trace
error.txt
Error Message
-------------
~/flask flask --help
Traceback (most recent call last):
File "/Users/username/.local/share/virtualenvs/flask-C1e3YqV7/lib/python3.7/site-packages/flask/cli.py", line 529, in list_commands
rv.update(info.load_app().cli.list_commands(ctx))
File "/Users/username/.local/share/virtualenvs/flask-C1e3YqV7/lib/python3.7/site-packages/flask/cli.py", line 384, in load_app
'Could not locate a Flask application. You did not provide '
flask.cli.NoAppException: Could not locate a Flask application. You did not provide the "FLASK_APP" environment variable, and a "wsgi.py" or "app.py" module was not found in the current directory.
Usage: flask [OPTIONS] COMMAND [ARGS]...
A general utility script for Flask applications.
Provides commands from Flask, extensions, and the application. Loads the
application defined in the FLASK_APP environment variable, or from a
wsgi.py file. Setting the FLASK_ENV environment variable to 'development'
will enable debug mode.
$ export FLASK_APP=hello.py
$ export FLASK_ENV=development
$ flask run
Options:
--version Show the flask version
--help Show this message and exit.
Commands:
routes Show the routes for the app.
run Runs a development server.
shell Runs a shell in the app context.
Minimal Reproduction
repro.py
# there is no FLASK_APP env var
$ flask --help Sat 28 Apr 2018 01:25:50 PM -03
Traceback (most recent call last):
File "~Projects/personal/flasgger/venv/lib/python3.6/site-packages/flask/cli.py", line 235, in locate_app
__import__(module_name)
ModuleNotFoundError: No module named 'app'
During handling of the above exception, another exception occurred:
Traceback (most recent call last):
File "~/Projects/personal/flasgger/venv/lib/python3.6/site-packages/flask/cli.py", line 529, in list_commands
rv.update(info.load_app().cli.list_commands(ctx))
File "~/Projects/personal/flasgger/venv/lib/python3.6/site-packages/flask/cli.py", line 372, in load_app
app = locate_app(self, import_name, name)
File "~/Projects/personal/flasgger/venv/lib/python3.6/site-packages/flask/cli.py", line 246, in locate_app
'Could not import "{name}".'.format(name=module_name)
flask.cli.NoAppException: Could not import "app".
Usage: flask [OPTIONS] COMMAND [ARGS]...
A general utility script for Flask applications.
Provides commands from Flask, extensions, and the application. Loads the
application defined in the FLASK_APP environment variable, or from a
wsgi.py file. Setting the FLASK_ENV environment variable to 'development'
will enable debug mode.
$ export FLASK_APP=hello.py
$ export FLASK_ENV=development
$ flask run
Options:
--version Show the flask version
--help Show this message and exit.
Commands:
routes Show the routes for the app.
run Runs a development server.
shell Runs a shell in the app context.
Environment
- Python: 3.6
What Broke
Users encountered raw tracebacks instead of helpful messages when running CLI commands without necessary environment variables.
Why It Broke
The CLI did not provide user-friendly error messages when the app failed to load due to missing environment variables
Fix Options (Details)
Option A — Upgrade to fixed release Safe default (recommended)
Upgrade to version 2.0.0 or later.
When NOT to use: This fix is not applicable if the application requires detailed tracebacks for debugging.
Use when you can deploy the upstream fix. It is usually lower-risk than long-lived workarounds.
Fix reference: https://github.com/pallets/flask/pull/3711
First fixed release: 2.0.0
Last verified: 2026-02-09. Validate in your environment.
When NOT to Use This Fix
- This fix is not applicable if the application requires detailed tracebacks for debugging.
Verify Fix
verify
Re-run: flask --help Sat 28 Apr 2018 01:25:50 PM -03
Did This Fix Work in Your Case?
Quick signal helps us prioritize which fixes to verify and improve.
Prevention
- Capture the exact failing error string in logs and tests so you can reproduce via a minimal script.
- Pin production dependencies and upgrade only with a reproducible test that hits the failing path.
Version Compatibility Table
| Version | Status |
|---|---|
| 2.0.0 | Fixed |
Related Issues
No related fixes found.
Sources
We don’t republish the full GitHub discussion text. Use the links above for context.