PrefectHQ/fastmcp · error · FileNotFoundError

Configuration file not found: {file_path}

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.

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)

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.

Related errors

• File {name!r} not found. Available: {available}
• resource_uri cannot be set on resources — the resource itsel
• visibility cannot be set on resources — it only applies to t
• ToolTransform has duplicate target name {target!r}: both {se
• At least one of version_gte or version_lt must be specified

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