PrefectHQ/fastmcp · error · RuntimeError

Failed to initialize project: {e.stderr}

Error message

Failed to initialize project: {e.stderr}

What it means

During `prepare()`, the environment runs `uv init` (via subprocess) to create the persistent project directory. If that command fails, the code checks whether stderr contains 'already initialized' (benign) and otherwise logs and re-raises RuntimeError with the captured stderr so the underlying uv failure is visible.

Source

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

                    "init",
                    "--project",
                    str(output_dir),
                    "--name",
                    "fastmcp-env",
                ],
                check=True,
                capture_output=True,
                text=True,
            )
        except subprocess.CalledProcessError as e:
            # If project already exists, that's fine - continue
            if "already initialized" in e.stderr.lower():
                logger.debug(
                    f"Project already initialized at {output_dir}, continuing..."
                )
            else:
                logger.error(f"Failed to initialize project: {e.stderr}")
                raise RuntimeError(f"Failed to initialize project: {e.stderr}") from e

        # Pin Python version if specified
        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,
                )

View on GitHub (pinned to 1f02114297)

Solutions

1. Read the stderr in the exception message and fix the underlying `uv init` failure (permissions, existing conflicting pyproject.toml, etc.).
2. Ensure output_dir is writable and does not contain a conflicting/invalid project — or clean it out.
3. Upgrade uv to the latest version (`uv self update` or reinstall) so error text and behavior match.
4. Run `uv init <output_dir>` manually to reproduce and see the full error.

Example fix

// before (CI)
- run: fastmcp run server.py
// after
- run: rm -rf .fastmcp-env && uv self update
- run: fastmcp run server.py

import subprocess
def preflight_uv_init(output_dir):
    r = subprocess.run(['uv', 'init', str(output_dir)], capture_output=True, text=True)
    if r.returncode != 0 and 'already initialized' not in r.stderr.lower():
        raise RuntimeError(f'uv init would fail: {r.stderr}')

try:
    env.prepare(output_dir=dir)
except RuntimeError as e:
    if 'Failed to initialize project' in str(e):
        shutil.rmtree(dir, ignore_errors=True)
        env.prepare(output_dir=dir)
    else:
        raise

When it happens

Trigger: `uv init` exiting non-zero for reasons other than 'already initialized' — e.g. output_dir not writable, output_dir contains conflicting files, malformed pyproject.toml in the target, disk full, or an incompatible/old uv version.

Common situations: Pointing output_dir at a directory that already has a broken/partial project; read-only or permission-restricted directories; corporate proxies blocking uv's network access during init; stale uv version whose error text differs so the benign case isn't matched.

Related errors

• uv is not installed. Please install it with: curl -LsSf http
• Failed to pin Python version: {e.stderr}
• Could not restrict access to CLI state
• Failed to add dependencies: {e.stderr}
• Failed to add requirements: {e.stderr}

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