{"record":{"id":"837b33b5a6b86ae9","repo":"PrefectHQ/fastmcp","slug":"configuration-file-not-found-file-path","errorCode":null,"errorMessage":"Configuration file not found: {file_path}","messagePattern":"Configuration file not found: (.+?)","errorType":"exception","errorClass":"FileNotFoundError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py","lineNumber":238,"sourceCode":"        return cast(Deployment, v)  # type: ignore[return-value]  # ty:ignore[redundant-cast]\n\n    @classmethod\n    def from_file(cls, file_path: Path) -> MCPServerConfig:\n        \"\"\"Load configuration from a JSON file.\n\n        Args:\n            file_path: Path to the configuration file\n\n        Returns:\n            MCPServerConfig instance\n\n        Raises:\n            FileNotFoundError: If the file doesn't exist\n            json.JSONDecodeError: If the file is not valid JSON\n            pydantic.ValidationError: If the configuration is invalid\n        \"\"\"\n        if not file_path.exists():\n            raise FileNotFoundError(f\"Configuration file not found: {file_path}\")\n\n        with file_path.open(\"r\", encoding=\"utf-8\") as f:\n            data = json.load(f)\n\n        return cls.model_validate(data)\n\n    @classmethod\n    def from_cli_args(\n        cls,\n        source: FileSystemSource,\n        transport: Literal[\"stdio\", \"http\", \"sse\", \"streamable-http\"] | None = None,\n        host: str | None = None,\n        port: int | None = None,\n        path: str | None = None,\n        log_level: Literal[\"DEBUG\", \"INFO\", \"WARNING\", \"ERROR\", \"CRITICAL\"]\n        | None = None,\n        python: str | None = None,\n        dependencies: list[str] | None = None,","sourceCodeStart":220,"sourceCodeEnd":256,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py#L220-L256","documentation":"FastMCPConfiguration.from_file raises FileNotFoundError when the config file passed via file_path does not exist on disk. The method checks file_path.exists() before opening, so this error means the path you supplied could not be found at the exact moment of the call. It is an intentional, documented failure (see the method's Raises section) so you get a clear message naming the missing file instead of an opaque OS error.","triggerScenarios":"Calling FastMCPConfiguration.from_file('/path/to/config.json') (or the CLI/server startup that uses it, e.g. `fastmcp run config.json` or loading an MCP server config) where the file does not exist at that path — deleted file, wrong cwd, typo, or missing mount in a container.","commonSituations":"Running the server from a different working directory than the one used to write the config; passing a relative path in Docker/CI where the file was never copied into the image; typos like 'mcp-server-conf.json' vs 'mcp-server-config.json'; using an old path after a project rename.","solutions":["Verify the exact path with `ls -la <file_path>` from the same working directory the process runs in; correct the path if it's wrong.","Convert relative paths to absolute (or `Path(__file__).parent / 'config.json'`) so the lookup is independent of cwd.","If running in Docker/CI, ensure the config file is copied/mounted into the container (COPY in Dockerfile, volume mount, artifact download).","Check file permissions/existence programmatically before calling from_file.","Pass an explicit cwd to your runner (e.g. `fastmcp run` from the project root) if you rely on relative paths."],"exampleFix":"// before\nconfig = FastMCPConfiguration.from_file(\"server.json\")\n\n// after\nfrom pathlib import Path\ncfg_path = Path(__file__).parent / \"configs\" / \"server.json\"\nif not cfg_path.exists():\n    raise SystemExit(f\"Config missing: {cfg_path}\")\nconfig = FastMCPConfiguration.from_file(cfg_path)","handlingStrategy":"validation","validationCode":"from pathlib import Path\n\ndef ensure_config(path: str | Path) -> Path:\n    p = Path(path).expanduser().resolve()\n    if not p.is_file():\n        raise SystemExit(f\"Config file missing: {p}\")\n    return p\n\nconfig = FastMCPConfiguration.from_file(ensure_config(\"server.json\"))","typeGuard":"def config_file_exists(path: str | Path) -> bool:\n    p = Path(path)\n    return p.exists() and p.is_file()","tryCatchPattern":"try:\n    config = FastMCPConfiguration.from_file(cfg_path)\nexcept FileNotFoundError as e:\n    logger.error(\"Config not found: %s (cwd=%s)\", e.filename, Path.cwd())\n    sys.exit(2)","preventionTips":["Use absolute paths built from __file__ or a known root instead of cwd-relative paths.","Check the file exists (and log cwd) in app startup before any config load.","In containers/CI, assert the config is copied/mounted as a build or job step.","Keep config filenames in a single constant to avoid typos."],"tags":["config","file-not-found","python"],"backgroundTag":"config-file-not-found","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}