{"record":{"id":"141828d6ec4dda64","repo":"pallets/flask","slug":"could-not-locate-a-flask-application-use-the-fla","errorCode":null,"errorMessage":"Could not locate a Flask application. Use the 'flask --app' option, 'FLASK_APP' environment variable, or a 'wsgi.py' or 'app.py' file in the current directory.","messagePattern":"Could not locate a Flask application\\. Use the 'flask --app' option, 'FLASK_APP' environment variable, or a 'wsgi\\.py' or 'app\\.py' file in the current directory\\.","errorType":"exception","errorClass":"NoAppException","httpStatus":null,"severity":"error","filePath":"src/flask/cli.py","lineNumber":359,"sourceCode":"        if self.create_app is not None:\n            app = self.create_app()\n        else:\n            if self.app_import_path:\n                path, name = (\n                    re.split(r\":(?![\\\\/])\", self.app_import_path, maxsplit=1) + [None]\n                )[:2]\n                import_name = prepare_import(path)\n                app = locate_app(import_name, name)\n            else:\n                for path in (\"wsgi.py\", \"app.py\"):\n                    import_name = prepare_import(path)\n                    app = locate_app(import_name, None, raise_if_not_found=False)\n\n                    if app is not None:\n                        break\n\n        if app is None:\n            raise NoAppException(\n                \"Could not locate a Flask application. Use the\"\n                \" 'flask --app' option, 'FLASK_APP' environment\"\n                \" variable, or a 'wsgi.py' or 'app.py' file in the\"\n                \" current directory.\"\n            )\n\n        if self.set_debug_flag:\n            # Update the app's debug flag through the descriptor so that\n            # other values repopulate as well.\n            app.debug = get_debug_flag()\n\n        self._loaded_app = app\n        return app\n\n\npass_script_info = click.make_pass_decorator(ScriptInfo, ensure=True)\n\nF = t.TypeVar(\"F\", bound=t.Callable[..., t.Any])","sourceCodeStart":341,"sourceCodeEnd":377,"githubUrl":"https://github.com/pallets/flask/blob/3596b1ab61cea85edb8970e83ff61daa073facf8/src/flask/cli.py#L341-L377","documentation":"ScriptInfo.load_app() tries, in order: create_app callback, the --app/FLASK_APP import path, then the default files wsgi.py and app.py in the current directory (with raise_if_not_found=False so a missing default is silent). If after all of these app is still None, Flask raises NoAppException telling you how to specify the app.","triggerScenarios":"Running any flask CLI command (flask run, flask routes, etc.) without --app/FLASK_APP set and without a wsgi.py or app.py file in the current directory, and no create_app registered on ScriptInfo. Each default-file locate_app returned None because raise_if_not_found=False suppressed the ImportError.","commonSituations":"New project where the app lives in mypkg/__init__.py but no app.py/wsgi.py exists in cwd. Renaming the entry file so the auto-detection no longer finds it. Forgetting to export FLASK_APP in a new shell session.","solutions":["Set FLASK_APP to your app location: export FLASK_APP='mypkg'.","Use the --app CLI flag: flask --app mypkg run.","Create an app.py or wsgi.py in the project root that imports and exposes the Flask app instance."],"exampleFix":"# before: app lives in mypkg/__init__.py, no app.py in cwd\nflask run   # -> Could not locate a Flask application\n\n# after\nexport FLASK_APP='mypkg'\nflask run","handlingStrategy":"validation","validationCode":"import os\n\ndef flask_app_locatable() -> bool:\n    if os.environ.get('FLASK_APP'):\n        return True\n    return os.path.exists('app.py') or os.path.exists('wsgi.py')","typeGuard":"null","tryCatchPattern":"from flask.cli import NoAppException\ntry:\n    script_info.load_app()\nexcept NoAppException:\n    os.environ['FLASK_APP'] = 'mypkg'\n    raise","preventionTips":["Always set FLASK_APP in your .env/flaskenv or create app.py at the project root.","Add a startup test that asserts flask CLI can locate the app in CI."],"tags":["flask","cli","app-resolution","configuration","environment"],"backgroundTag":null,"analyzedSha":"3596b1ab61cea85edb8970e83ff61daa073facf8","analyzedAt":"2026-08-11T20:11:52.622Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}