asdf-vm/asdf · error

unable to clone plugin: %s

Error message

unable to clone plugin: %s

What it means

git.Clone runs `git clone` (optionally with --depth 1 and --branch <ref>) to fetch a plugin repository into its local directory. If the git command exits non-zero, the stderr output is surfaced as "unable to clone plugin: <message>".

Source

Thrown at internal/git/git.go:52

	URL       string
}

// NewRepo builds a new Repo instance
func NewRepo(directory string) Repo {
	return Repo{Directory: directory}
}

// Clone installs a plugin via Git
func (r Repo) Clone(pluginURL, ref string) error {
	cmdStr := []string{"git", "clone", "--depth", "1", pluginURL, r.Directory}

	if ref != "" {
		cmdStr = []string{"git", "clone", "--depth", "1", pluginURL, r.Directory, "--branch", ref}
	}

	_, stderr, err := exec(cmdStr)
	if err != nil {
		return fmt.Errorf("unable to clone plugin: %s", stdErrToErrMsg(stderr))
	}

	return nil
}

// Head returns the current HEAD ref of the plugin's Git repository
func (r Repo) Head() (string, error) {
	err := repositoryExists(r.Directory)
	if err != nil {
		return "", err
	}

	stdout, stderr, err := exec([]string{"git", "-C", r.Directory, "rev-parse", "HEAD"})
	if err != nil {
		return "", errors.New(stdErrToErrMsg(stderr))
	}

	return strings.TrimSpace(stdout), nil

View on GitHub (pinned to 074a1722ca)

Solutions

1. Verify the plugin URL and that the repo/branch exists; re-run with the corrected URL.
2. Check network/proxy/SSL settings; test `git clone <url>` manually to see the raw error.
3. For private repos configure SSH keys or credentials before `asdf plugin add`.
4. Remove a stale target directory and retry: `rm -rf ~/.asdf/plugins/<name>` then re-add.

Example fix

# before
asdf plugin add nodejs https://wrong-url.example/nodejs.git
# after
asdf plugin add nodejs https://github.com/asdf-vm/asdf-nodejs.git

git ls-remote "$PLUGIN_URL" >/dev/null 2>&1 || { echo "unreachable: $PLUGIN_URL"; exit 1; }
command -v git >/dev/null || { echo "git required"; exit 1; }

for i in 1 2 3; do
  asdf plugin add "$NAME" "$URL" && break
  sleep $((i * 2))
done

When it happens

Trigger: Plugin URL is wrong or the repo doesn't exist; no network access or a proxy blocks github.com; the requested --branch ref does not exist; target directory is not writable or already exists non-empty; git not installed or auth required for a private repo.

Common situations: Typos in `asdf plugin add <name> <url>`; corporate firewalls/SSL interception; cloning a private plugin repo without credentials; shallow clone of a ref that was force-removed upstream.

Related errors

• unable to resolve plugin new Git HEAD: %w
• unable to initialize index: %w
• unable to update plugin index: %w
• error fetching plugin URL: %s
• no plugin name specified

AI-assisted analysis of asdf-vm/asdf@074a1722ca (2026-08-30). Data as JSON: /api/errors/346f3b438bfc7ac3. Report an issue: GitHub.