astral-sh/ruff · error · std::io::Error

failed to resolve uv executable: {error}

Error message

failed to resolve uv executable: {error}

What it means

ty's project system builds an error when it cannot locate the `uv` executable on the system. `uv_executable_error` wraps a `WhichError` (from the `which` crate) into a `std::io::Error` with kind `NotFound`, meaning commands that need to spawn uv (synchronization, metadata resolution) cannot proceed because no uv binary was found on PATH.

Source

Thrown at crates/ty_project/src/uv/command.rs:118

    }
}

/// The workspace or standalone script for which to request uv metadata.
#[derive(Debug)]
pub(crate) enum MetadataTarget<'path> {
    /// The directory from which uv discovers the workspace, not necessarily the workspace root.
    Workspace(&'path SystemPath),
    /// A standalone Python script.
    Script {
        /// The script file passed to `--script`.
        path: &'path SystemPath,
        /// The optional `--python` argument.
        python: Option<&'path SystemPath>,
    },
}

pub(crate) fn uv_executable_error(error: WhichError) -> std::io::Error {
    std::io::Error::new(
        std::io::ErrorKind::NotFound,
        format!("failed to resolve uv executable: {error}"),
    )
}

pub(super) fn unsupported_command_execution() -> std::io::Error {
    std::io::Error::new(
        std::io::ErrorKind::Unsupported,
        "running commands is not supported by this system",
    )
}

#[cfg(test)]
mod tests {
    use ruff_db::system::TestSystem;
    use ty_static::EnvVars;

    use super::Uv;

View on GitHub (pinned to 26f38c119c)

Solutions

1. Install uv (e.g. `pip install uv`, `cargo install uv`, or the official installer) or point the project to an environment that does not require uv.
2. Ensure the uv binary is on the PATH of the process running ty (IDE-spawned servers may need PATH configured in the IDE settings).
3. Verify with `which uv` / `uv --version` in the same environment ty runs in.
4. If uv cannot be installed, switch the project configuration to a non-uv interpreter setup.

Example fix

// before: ty project requires uv but it is absent
// after (shell)
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"  # ensure ty's process can see it

# shell: verify uv is resolvable in the exact environment ty runs in
command -v uv >/dev/null 2>&1 || { echo 'uv not found on PATH'; exit 1; }
uv --version

// Rust caller: match on the io::ErrorKind::NotFound to give actionable guidance
match result {
  Err(e) if e.kind() == std::io::ErrorKind::NotFound => {
    eprintln!("uv is not installed or not on PATH; install uv or disable uv sync")
  }
  other => other?,
}

When it happens

Trigger: ty attempts to run `uv` (e.g. for environment sync or package metadata) and the `which`-based lookup fails — uv is not installed, not on PATH, or not executable. Raised via `uv_executable_error` in `crates/ty_project/src/uv/command.rs:118`.

Common situations: Projects configured to use uv in environments where uv is not installed; CI containers without uv on PATH; PATH differences between the shell and the IDE-spawned ty process; uv installed via a tool manager that ty's environment doesn't inherit.

Related errors

• NotFound
• InternalError
• uv was not found; is it installed and on the PATH?
• Expected uv to create a lockfile at '{}'
• InvalidInput

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