OpenBB-finance/OpenBB · error · RuntimeError

Failed to load the file specs for '{file_path}'

Error message

Failed to load the file specs for '{file_path}'

What it means

RuntimeError raised by the helper that imports a FastAPI app from a file path when importlib.util.spec_from_file_location returns None. That happens when the path does not point to a loadable Python source file (wrong extension, directory, or unreadable/nonexistent file), so no import spec can be constructed.

Source

Thrown at openbb_platform/extensions/mcp_server/openbb_mcp_server/utils/app_import.py:33

    def _is_module_colon_notation(app_path: str) -> bool:
        """Check if the path uses module:name notation vs a Windows path."""
        if ":" not in app_path:
            return False
        # Windows absolute path check (e.g., C:\path or D:/path)
        if len(app_path) >= 2 and app_path[1] == ":" and app_path[0].isalpha():
            # Could still have colon notation: C:\path\file.py:app
            parts = app_path.split(":")
            return len(parts) > 2  # More than just drive letter colon
        return True

    def _load_module_from_file_path(file_path: str):
        """Load a Python module from a file path."""
        spec_name = os.path.basename(file_path).split(".")[0]
        spec = util.spec_from_file_location(spec_name, file_path)

        if spec is None:
            raise RuntimeError(f"Failed to load the file specs for '{file_path}'")

        module = util.module_from_spec(spec)  # type: ignore
        sys.modules[spec_name] = module  # type: ignore
        spec.loader.exec_module(module)  # type: ignore
        return module

    # Case 1: Module path with colon notation (e.g., "my_app.main:app" or "main:app")
    if _is_module_colon_notation(app_path):
        module_path, name = app_path.rsplit(":", 1)
        try:  # First try to import as a module
            module = import_module(module_path)
        except ImportError:  # If module import fails, try to load as a local file
            if not module_path.endswith(".py"):
                module_path += ".py"

            if not Path(module_path).is_absolute():
                cwd = Path.cwd()
                file_path = str(cwd.joinpath(module_path).resolve())

View on GitHub (pinned to 3e071fcc2c)

Solutions

  1. Point --app at an actual Python file ending in .py, e.g. --app ./my_app/main.py
  2. If you meant a package, use module notation with a colon: --app my_app.main:app
  3. Verify the path exists and is readable: os.path.isfile(path) before invoking the server

Example fix

# before
openbb-mcp --app ./my_app

# after
openbb-mcp --app ./my_app/main.py --name app
Defensive patterns

Strategy: type-guard

Validate before calling

from pathlib import Path

p = Path(app_path)
if not p.is_file() or p.suffix != ".py":
    raise ValueError(f"--app must point to a .py file, got: {app_path}")

Type guard

def is_loadable_py_file(path: str) -> bool:
    p = Path(path)
    return p.is_file() and p.suffix == ".py" and os.access(p, os.R_OK)

Try / catch

try:
    app = import_app("./main.py", "app")
except RuntimeError as e:
    if "Failed to load the file specs" in str(e):
        raise SystemExit(
            f"'{app_path}' is not a loadable .py file — check extension and path"
        ) from e
    raise

Prevention

When it happens

Trigger: Calling the CLI/import helper with --app pointing at a directory, a .txt/.json file, or a path with no read permission; spec_from_file_location only recognizes real .py source (or importable extensions), so anything else yields None.

Common situations: Passing a package directory instead of its entry module (./my_app instead of ./my_app/main.py), typos in the file extension, running from a different working directory with a relative path that resolves to nothing, files on mounts that report stale metadata.

Related errors

AI-assisted analysis of OpenBB-finance/OpenBB@3e071fcc2c (2026-08-14). Data as JSON: /api/errors/e39d6d16f876eeb3. Report an issue: GitHub.