PrefectHQ/fastmcp · error · FileNotFoundError

Configuration file not found

Error message

Configuration file not found: {file_path}

What it means

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.

Solutions

1. 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.
2. Convert relative paths to absolute (or `Path(__file__).parent / 'config.json'`) so the lookup is independent of cwd.
3. If running in Docker/CI, ensure the config file is copied/mounted into the container (COPY in Dockerfile, volume mount, artifact download).
4. Check file permissions/existence programmatically before calling from_file.
5. Pass an explicit cwd to your runner (e.g. `fastmcp run` from the project root) if you rely on relative paths.

Example fix

// before
config = FastMCPConfiguration.from_file("server.json")

// after
from pathlib import Path
cfg_path = Path(__file__).parent / "configs" / "server.json"
if not cfg_path.exists():
    raise SystemExit(f"Config missing: {cfg_path}")
config = FastMCPConfiguration.from_file(cfg_path)

from pathlib import Path

def ensure_config(path: str | Path) -> Path:
    p = Path(path).expanduser().resolve()
    if not p.is_file():
        raise SystemExit(f"Config file missing: {p}")
    return p

config = FastMCPConfiguration.from_file(ensure_config("server.json"))

def config_file_exists(path: str | Path) -> bool:
    p = Path(path)
    return p.exists() and p.is_file()

try:
    config = FastMCPConfiguration.from_file(cfg_path)
except FileNotFoundError as e:
    logger.error("Config not found: %s (cwd=%s)", e.filename, Path.cwd())
    sys.exit(2)

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "Config file not found": what it means and how to fix it in docker-sync, Maven, Vagrant, Turborepo and other tools — this error's family across 60 libraries.

Related errors

• At least one of version_gte or version_lt must be specified
• File not found. Available
• No server specification or fastmcp.json found
• resource_uri cannot be set on resources — the resource…
• ToolTransform has duplicate target name

AI-assisted analysis of PrefectHQ/fastmcp@1f02114297 (2026-08-29). Data as JSON: /api/errors/837b33b5a6b86ae9. Report an issue: GitHub.

Appendix: source

Thrown at fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/mcp_server_config.py:238

        return cast(Deployment, v)  # type: ignore[return-value]  # ty:ignore[redundant-cast]

    @classmethod
    def from_file(cls, file_path: Path) -> MCPServerConfig:
        """Load configuration from a JSON file.

        Args:
            file_path: Path to the configuration file

        Returns:
            MCPServerConfig instance

        Raises:
            FileNotFoundError: If the file doesn't exist
            json.JSONDecodeError: If the file is not valid JSON
            pydantic.ValidationError: If the configuration is invalid
        """
        if not file_path.exists():
            raise FileNotFoundError(f"Configuration file not found: {file_path}")

        with file_path.open("r", encoding="utf-8") as f:
            data = json.load(f)

        return cls.model_validate(data)

    @classmethod
    def from_cli_args(
        cls,
        source: FileSystemSource,
        transport: Literal["stdio", "http", "sse", "streamable-http"] | None = None,
        host: str | None = None,
        port: int | None = None,
        path: str | None = None,
        log_level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]
        | None = None,
        python: str | None = None,
        dependencies: list[str] | None = None,

View on GitHub (pinned to 1f02114297)