{"record":{"id":"077560a26c2e9300","repo":"PrefectHQ/fastmcp","slug":"failed-to-reload-module-file-path-e","errorCode":null,"errorMessage":"Failed to reload module {file_path}: {e}","messagePattern":"Failed to reload module (.+?): (.+?)","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/server/providers/filesystem_discovery.py","lineNumber":263,"sourceCode":"            sys.path.insert(0, parent_dir)\n\n        try:\n            spec = importlib.util.spec_from_file_location(module_name, file_path)\n            if spec is None or spec.loader is None:\n                raise ImportError(f\"Cannot load spec for {file_path}\")\n\n            existing = sys.modules.get(module_name)\n            if existing is not None:\n                # Re-exec in place rather than importlib.reload: reload() re-finds\n                # the module by name via sys.path, which fails for private keys\n                # (the file is tool.py, not _fastmcp_tool_xxx.py).\n                existing.__spec__ = spec\n                existing.__loader__ = spec.loader\n                existing.__file__ = str(file_path)\n                try:\n                    spec.loader.exec_module(existing)\n                except Exception as e:\n                    raise ImportError(\n                        f\"Failed to reload module {file_path}: {e}\"\n                    ) from e\n                return existing\n\n            module = importlib.util.module_from_spec(spec)\n            sys.modules[module_name] = module\n\n            try:\n                spec.loader.exec_module(module)\n            except Exception as e:\n                # Clean up sys.modules on failure\n                sys.modules.pop(module_name, None)\n                raise ImportError(f\"Failed to execute module {file_path}: {e}\") from e\n\n            return module\n        finally:\n            if path_added:\n                with contextlib.suppress(ValueError):","sourceCodeStart":245,"sourceCodeEnd":281,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/server/providers/filesystem_discovery.py#L245-L281","documentation":"When the module was already imported (hot-reload path), FastMCP re-execs it in place by resetting `__spec__`/`__loader__`/`__file__` and calling `spec.loader.exec_module`. Any exception during that re-execution — not just ImportError — is wrapped in this ImportError with the file path.","triggerScenarios":"Reload of an existing module whose new source raises at import time: NameError, SyntaxError, missing dependency, or module-level code that fails (e.g. connecting to a service).","commonSituations":"Editing a tool file and introducing a typo or undefined name; reloading after renaming an imported helper; module-level side effects (DB connections) failing on reload.","solutions":["Fix the error in the source file — the chained cause shows the original exception and line","Validate the file compiles before saving: `python -m py_compile plugin.py`","Avoid module-level side effects; move connection/startup logic into functions","Re-trigger discovery once the file is fixed so the module re-executes cleanly"],"exampleFix":"// before\n# plugin.py (edited)\ndef tool(): ...\nrun_setup()  # NameError: run_setup was deleted\n// after\n# plugin.py\ndef tool(): ...  # remove the call or re-import run_setup","handlingStrategy":"try-catch","validationCode":"import py_compile\npy_compile.compile('plugin.py', doraise=True)  # raises on syntax errors before reload","typeGuard":null,"tryCatchPattern":"try:\n    mod = provider.import_module_from_file(path)  # reload path\nexcept ImportError as e:\n    log.error('reload of %s failed: %s', path, e.__cause__)\n    # keep serving the previous module version; fix source before retrying","preventionTips":["Keep module-level code free of side effects and failures","Compile-check files before saving to the watched directory","Avoid deleting/moving helper modules that loaded files import"],"tags":["python","reload","hot-reload","module-loading"],"backgroundTag":"module-reload-execution-failed","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}