What causes "Failed to clone repository from GitHub." in astrid-runtime/astrid?

Run the same `git clone --depth 1 ` manually to see git's actual error message

Failed to clone repository from GitHub.

Error message

Failed to clone repository from GitHub.

What it means

`clone_and_build` shells out to `git clone --depth 1 <url>` into a temp directory and bails with this message when the clone subprocess reports non-zero exit status. The error is generic by design — git's own diagnostics are printed to stderr by the child process, and this message just signals that the clone step of source-based capsule installation failed.

Source

Thrown at crates/astrid-cli/src/commands/capsule/install.rs:574

/// Clone a GitHub repository and build the capsule from source using
/// `astrid-build`. Returns the installed capsule id.
async fn clone_and_build(
    url: &str,
    repo: &str,
    name_hint: Option<&str>,
    context: InstallContext<'_>,
) -> anyhow::Result<InstalledCapsuleOutcome> {
    let tmp_dir = tempfile::tempdir().context("failed to create temp dir for cloning")?;
    let clone_dir = tmp_dir.path().join(repo);

    let status = std::process::Command::new("git")
        .args(["clone", "--depth", "1", url, &clone_dir.to_string_lossy()])
        .status()
        .context("Failed to spawn git clone")?;

    if !status.success() {
        bail!("Failed to clone repository from GitHub.");
    }

    let output_dir = tmp_dir.path().join("dist");
    std::fs::create_dir_all(&output_dir)?;

    let build_bin = crate::bootstrap::find_companion_binary("astrid-build")?;
    let build_status = std::process::Command::new(build_bin)
        .arg(clone_dir.to_str().context("Invalid clone dir path")?)
        .arg("--output")
        .arg(output_dir.to_str().context("Invalid output dir path")?)
        .status()
        .context("Failed to run astrid-build")?;
    if !build_status.success() {
        bail!(
            "astrid-build failed with exit code {}",
            build_status.code().unwrap_or(1)
        );
    }

View on GitHub (pinned to affd8760f4)

Solutions

Run the same `git clone --depth 1 <url>` manually to see git's actual error message
Verify the repo URL exists and is spelled correctly (org/repo) on github.com
If the repo is private, configure credentials: `gh auth login` or set up SSH keys / a credential helper so git can authenticate
Check network connectivity / proxy settings (HTTPS_PROXY, corporate firewall) that may block github.com
Ensure the temp clone directory does not already exist or is writable

Example fix

// before: private repo, no credentials → clone fails
astrid capsule install github:myorg/private-capsule
// after: authenticate git first
gh auth login
astrid capsule install github:myorg/private-capsule

Defensive patterns

Strategy: try-catch

Validate before calling

// Verify reachability and credentials before install
let url = format!("https://github.com/{org}/{repo}");
let ok = std::process::Command::new("git")
    .args(["ls-remote", &url])
    .status()
    .map(|s| s.success())
    .unwrap_or(false);
if !ok { eprintln!("cannot access {url}: check repo exists and git auth is configured"); }

Try / catch

match clone_and_build(url, ...) {
    Ok(id) => proceed(id),
    Err(e) if e.to_string().contains("Failed to clone repository") => {
        // git's real error was on stderr: advise running
        // `git clone --depth 1 {url}` manually to see it
    }
    Err(e) => return Err(e),
}

Prevention

Test `git ls-remote https://github.com/org/repo` before scripted installs to catch auth/network issues early
Run `gh auth login` or configure SSH keys when installing from private repos
Check git is installed and on PATH (`git --version`) in CI or container environments
Validate the org/repo URL in config to avoid typos and renamed repositories

When it happens

Trigger: Installing a capsule from a GitHub source URL when `git clone` exits non-zero: the repository does not exist or is private, no network access, bad URL, git not handling credentials for a private repo, or the local clone directory already exists.

Common situations: Typo in the org/repo URL; attempting to install a private capsule repo without GitHub credentials configured (no SSH key / no gh auth); corporate proxy or offline environment blocking github.com; repo renamed or deleted.

Understand the failure class

Background: "git command failed": what it means when a tool shells out to git and git exits non-zero — this error's family across 21 libraries.

Related errors

AI-assisted analysis of astrid-runtime/astrid@affd8760f4 (2026-09-09). Data as JSON: /api/errors/517e71432fda3577. Report an issue: GitHub.