PrefectHQ/fastmcp · error · RuntimeError

Failed to pin Python version: {e.stderr}

Error message

Failed to pin Python version: {e.stderr}

What it means

FastMCP's UVEnvironment.prepare() runs `uv python pin <version> --project <dir>` and raises this RuntimeError if uv exits nonzero. It means uv could not pin the requested Python version in the generated fastmcp-env project, aborting environment preparation. The uv stderr is included in the message.

Source

Thrown at fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/uv.py:184

        if self.python:
            logger.debug(f"Pinning Python version to {self.python}")
            try:
                subprocess.run(
                    [
                        "uv",
                        "python",
                        "pin",
                        self.python,
                        "--project",
                        str(output_dir),
                    ],
                    check=True,
                    capture_output=True,
                    text=True,
                )
            except subprocess.CalledProcessError as e:
                logger.error(f"Failed to pin Python version: {e.stderr}")
                raise RuntimeError(f"Failed to pin Python version: {e.stderr}") from e

        # Add dependencies with --no-sync to defer installation
        # dependencies ALWAYS include fastmcp; this is compatible with
        # specific fastmcp versions that might be in the dependencies list
        dependencies = (self.dependencies or []) + ["fastmcp"]
        logger.debug(f"Adding dependencies: {', '.join(dependencies)}")
        try:
            subprocess.run(
                [
                    "uv",
                    "add",
                    *dependencies,
                    "--no-sync",
                    "--project",
                    str(output_dir),
                ],
                check=True,
                capture_output=True,

View on GitHub (pinned to 1f02114297)

Solutions

1. Read e.stderr in the message: if uv says it can't find/download the Python, run `uv python install <version>` manually once, then retry.
2. Fix the `python` value in the mcpServerConfig environment block to a valid version like "3.12" (no 'v' prefix, no patch-only invalid specs).
3. Update uv (`uv self update` or reinstall via the astral.sh installer) and retry; old uv builds may lack newer Python versions.
4. Check network/proxy settings (UV_PYTHON_INSTALL_MIRROR, HTTPS_PROXY) if the download is failing.
5. Remove the `python` field entirely if a specific version isn't required; prepare() skips pinning when it is None.

Example fix

// before (fastmcp.json)
"environment": { "type": "uv", "python": "v3.12" }

// after
"environment": { "type": "uv", "python": "3.12" }

import shutil, subprocess

assert shutil.which("uv"), "uv not installed"
version = cfg.environment.python
if version:
    r = subprocess.run(["uv", "python", "find", version], capture_output=True, text=True)
    if r.returncode != 0:
        print(f"Python {version} unavailable to uv: {r.stderr}")

try:
    await env.prepare(output_dir)
except RuntimeError as e:
    if str(e).startswith("Failed to pin Python version"):
        # inspect/fix env.python or install the interpreter, then retry
        ...
    else:
        raise

When it happens

Trigger: Calling prepare() (directly or via the fastmcp CLI running a server config) with environment.python set to a version uv cannot resolve: an uninstalled Python that uv cannot download, a malformed version string, or a corrupted/partial uv install.

Common situations: Config sets python: "3.13" in an offline/air-gapped environment where uv can't download the toolchain; typo like python: "v3.12"; corporate proxy blocking uv's Python downloads; uv too old to support the requested version.

Related errors

• Failed to initialize project: {e.stderr}
• Failed to add dependencies: {e.stderr}
• Failed to add requirements: {e.stderr}
• Failed to add editable packages: {e.stderr}
• Failed to sync dependencies: {e.stderr}

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