What causes "`uv sync` failed with exit code {:?}: {}" in astral-sh/ruff?

Read the stderr included in the message to identify uv's actual complaint

`uv sync` failed with exit code

Error message

`uv sync` failed with exit code {:?}:
{}

What it means

Generic failure path of setup_venv: after running `uv sync` to install the mdtest's external dependencies into a temporary venv, the command exited non-zero for any reason not covered by the lockfile checks, so the harness bails with uv's exit code and stderr.

Solutions

Read the stderr included in the message to identify uv's actual complaint
Check network/proxy access to the package index and retry
Fix unresolvable/conflicting dependency specs in the mdtest's external-dependencies declaration
Ensure a suitable `uv` is installed and on PATH (`uv --version`) and that a matching Python interpreter is available

Example fix

// diagnose
bash -c 'MDTEST_EXTERNAL=1 cargo test -p ty_python_semantic --test mdtest mdtest__external 2>&1 | tail -40'
// after fixing the underlying cause (e.g. corrected dependency spec)
---
external_dependencies:
  dependencies:
    - numpy==2.1.0   # was: numpy  (unpinned caused resolution failure)
---

Defensive patterns

Strategy: try-catch

Validate before calling

uv --version && uv python find  # confirm uv and a suitable interpreter exist

Try / catch

let output = std::process::Command::new("uv").args(["sync", "--locked"]).output()?;
if !output.status.success() {
    eprintln!("uv sync failed ({}): {}",
        output.status.code().unwrap_or(-1),
        String::from_utf8_lossy(&output.stderr));
}

Prevention

Ensure network/proxy access to the package index before running external mdtests
Keep `uv` up to date and on PATH; verify with `uv --version`
Pin mdtest dependency versions so resolution is deterministic
Read the stderr embedded in the message first — it names the underlying uv failure

When it happens

Trigger: `uv sync` fails inside setup_venv (crates/ty_test/src/external_dependencies.rs:123) due to network errors during dependency download, an unresolvable requirement set, a Python version mismatch with the venv, or uv not finding a valid interpreter.

Common situations: Working offline or behind a proxy that blocks PyPI; a dependency spec in the mdtest that cannot be resolved; an incompatible `requires-python` in the project; a broken or too-old `uv` on PATH.

Related errors

AI-assisted analysis of astral-sh/ruff@26f38c119c (2026-09-05). Data as JSON: /api/errors/466a71b323283641. Report an issue: GitHub.

Appendix: source

Thrown at crates/ty_test/src/external_dependencies.rs:123

    if !uv_sync_output.status.success() {
        let stderr = String::from_utf8_lossy(&uv_sync_output.stderr);

        if use_locked
            && stderr.contains("`uv.lock` needs to be updated, but `--locked` was provided.")
        {
            bail!(
                "Lockfile is out of date. Use one of these commands to regenerate it:\n\
                 \n\
                 uv run crates/ty_python_semantic/mdtest.py -e external/\n\
                 \n\
                 Or using cargo:\n\
                 \n\
                 MDTEST_EXTERNAL=1 MDTEST_UPGRADE_LOCKFILES=1 cargo test -p ty_python_semantic --test mdtest mdtest__external"
            );
        }

        bail!(
            "`uv sync` failed with exit code {:?}:\n{}",
            uv_sync_output.status.code(),
            stderr
        );
    }

    // In upgrade mode, copy the generated lockfile back to the source location
    if upgrade_lockfile {
        let temp_lockfile = temp_path.join("uv.lock");
        let temp_lockfile = temp_lockfile.as_std_path();
        if temp_lockfile.exists() {
            std::fs::copy(temp_lockfile, lockfile_path)
                .with_context(|| format!("Failed to write lockfile to '{lockfile_path}'"))?;
        } else {
            bail!(
                "Expected uv to create a lockfile at '{}'",
                temp_lockfile.display()
            );

View on GitHub (pinned to 26f38c119c)