{"record":{"id":"8194aaad8b726c6e","repo":"Textualize/textual","slug":"app-name-r-not-found-in-lib-r","errorCode":null,"errorMessage":"App {name!r} not found in {lib!r}","messagePattern":"App (.+?) not found in (.+?)","errorType":"exception","errorClass":"AppFail","httpStatus":null,"severity":"error","filePath":"src/textual/_import_app.py","lineNumber":76,"sourceCode":"    if drive:\n        lib = os.path.join(drive, os.sep, lib)\n\n    if lib.endswith(\".py\") or shebang_python(Path(lib)):\n        path = os.path.abspath(lib)\n        sys.path.append(str(Path(path).parent))\n        try:\n            global_vars = runpy.run_path(path, {})\n        except Exception as error:\n            raise AppFail(str(error))\n\n        sys.argv[:] = [path, *argv]\n\n        if name:\n            # User has given a name, use that\n            try:\n                app = global_vars[name]\n            except KeyError:\n                raise AppFail(f\"App {name!r} not found in {lib!r}\")\n        else:\n            # User has not given a name\n            if \"app\" in global_vars:\n                # App exists, lets use that\n                try:\n                    app = global_vars[\"app\"]\n                except KeyError:\n                    raise AppFail(f\"App {name!r} not found in {lib!r}\")\n            else:\n                # Find an App class or instance that is *not* the base class\n                apps = [\n                    value\n                    for value in global_vars.values()\n                    if (\n                        isinstance(value, App)\n                        or (inspect.isclass(value) and issubclass(value, App))\n                        and value is not App\n                    )","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/Textualize/textual/blob/06dbeef4bb70fb718236aa418ed658ef4667a126/src/textual/_import_app.py#L58-L94","documentation":"Raised by Textual's import_app() when an app is imported from a Python file (not an installed package) and the name given before the colon (e.g. \"foo.py:myapp\") does not exist as a global variable in that file. Textual loads the file with runpy and looks up the requested name in the module's global namespace, so a typo or an app that lives inside a function/if-main guard will not be found. The error is wrapped in AppFail, which is what CLI commands like `textual run` and the SVG screenshot tool report.","triggerScenarios":"Calling textual's take_svg_screenshot or `textual run foo.py:myapp` where foo.py has no module-level variable named myapp; the app is instantiated inside `if __name__ == \"__main__\":` so no global name exists; the name is misspelled or uses different casing than the variable in the file.","commonSituations":"Apps created from templates that define `class MyApp(App)` but never assign `app = MyApp()` at module level; renaming the app variable in the file but not in the CLI argument; passing a class name when the file only has an instance (or vice versa); running the screenshot command from a docs/snippet file where the app is defined inside a function.","solutions":["Verify the exact global name in the target file and use it after the colon: `textual run foo.py:app` where `app = MyApp()` exists at module level in foo.py","Add a module-level assignment `app = MyApp()` to the file","If you only have a class, either instantiate it at module level or pass the class-name variable that exists as a global","Omit the name entirely (just `foo.py`) so Textual auto-discovers a global `app` or a unique App subclass/instance"],"exampleFix":"# before\n# foo.py\nclass MyApp(App): ...\nif __name__ == \"__main__\":\n    MyApp().run()\n# CLI: textual run foo.py:app  -> AppFail\n\n# after\n# foo.py\nclass MyApp(App): ...\napp = MyApp()\n# CLI: textual run foo.py:app","handlingStrategy":"validation","validationCode":"import runpy, inspect\nfrom textual.app import App\n\ndef find_app_global(path: str, name: str) -> object | None:\n    g = runpy.run_path(path)\n    return g.get(name)","typeGuard":"def is_app(obj: object) -> TypeGuard[App]:\n    return isinstance(obj, App) or (inspect.isclass(obj) and issubclass(obj, App))","tryCatchPattern":"from textual.app import App\ntry:\n    app = import_app(\"foo.py:myapp\")\nexcept AppFail as e:\n    print(f\"Bad app reference: {e}\")  # prompt user / fix path:name","preventionTips":["Always assign `app = MyApp()` at module level in entry files","Standardize the variable name `app` across the project","In CI, import the entry file and assert `app` exists before running textual commands"],"tags":["textual","import","app-discovery","cli"],"backgroundTag":"symbol-not-found-in-module","analyzedSha":"06dbeef4bb70fb718236aa418ed658ef4667a126","analyzedAt":"2026-08-27T02:36:57.214Z","schemaVersion":2},"datasetVersion":"2026-08-27T03:17:27.898Z"}