{"record":{"id":"68ce6054a73da524","repo":"PrefectHQ/fastmcp","slug":"failed-to-pin-python-version-e-stderr","errorCode":null,"errorMessage":"Failed to pin Python version: {e.stderr}","messagePattern":"Failed to pin Python version: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/uv.py","lineNumber":184,"sourceCode":"        if self.python:\n            logger.debug(f\"Pinning Python version to {self.python}\")\n            try:\n                subprocess.run(\n                    [\n                        \"uv\",\n                        \"python\",\n                        \"pin\",\n                        self.python,\n                        \"--project\",\n                        str(output_dir),\n                    ],\n                    check=True,\n                    capture_output=True,\n                    text=True,\n                )\n            except subprocess.CalledProcessError as e:\n                logger.error(f\"Failed to pin Python version: {e.stderr}\")\n                raise RuntimeError(f\"Failed to pin Python version: {e.stderr}\") from e\n\n        # Add dependencies with --no-sync to defer installation\n        # dependencies ALWAYS include fastmcp; this is compatible with\n        # specific fastmcp versions that might be in the dependencies list\n        dependencies = (self.dependencies or []) + [\"fastmcp\"]\n        logger.debug(f\"Adding dependencies: {', '.join(dependencies)}\")\n        try:\n            subprocess.run(\n                [\n                    \"uv\",\n                    \"add\",\n                    *dependencies,\n                    \"--no-sync\",\n                    \"--project\",\n                    str(output_dir),\n                ],\n                check=True,\n                capture_output=True,","sourceCodeStart":166,"sourceCodeEnd":202,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/utilities/mcp_server_config/v1/environments/uv.py#L166-L202","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Fix the `python` value in the mcpServerConfig environment block to a valid version like \"3.12\" (no 'v' prefix, no patch-only invalid specs).","Update uv (`uv self update` or reinstall via the astral.sh installer) and retry; old uv builds may lack newer Python versions.","Check network/proxy settings (UV_PYTHON_INSTALL_MIRROR, HTTPS_PROXY) if the download is failing.","Remove the `python` field entirely if a specific version isn't required; prepare() skips pinning when it is None."],"exampleFix":"// before (fastmcp.json)\n\"environment\": { \"type\": \"uv\", \"python\": \"v3.12\" }\n\n// after\n\"environment\": { \"type\": \"uv\", \"python\": \"3.12\" }","handlingStrategy":"try-catch","validationCode":"import shutil, subprocess\n\nassert shutil.which(\"uv\"), \"uv not installed\"\nversion = cfg.environment.python\nif version:\n    r = subprocess.run([\"uv\", \"python\", \"find\", version], capture_output=True, text=True)\n    if r.returncode != 0:\n        print(f\"Python {version} unavailable to uv: {r.stderr}\")","typeGuard":null,"tryCatchPattern":"try:\n    await env.prepare(output_dir)\nexcept RuntimeError as e:\n    if str(e).startswith(\"Failed to pin Python version\"):\n        # inspect/fix env.python or install the interpreter, then retry\n        ...\n    else:\n        raise","preventionTips":["Use plain version strings like \"3.12\" (no 'v' prefix) in environment.python","Pre-install interpreters with `uv python install 3.12` before deploying offline","Keep uv updated so new Python versions are resolvable","Omit `python` when any available version works"],"tags":["uv","python-version","subprocess","environment-setup"],"backgroundTag":"uv-python-pin-failed","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}