What causes "unable to initialize index: %w" in asdf-vm/asdf?

Verify network connectivity to the index host (e.g. git ls-remote ).

unable to initialize index

Error message

unable to initialize index: %w

What it means

PluginIndex.Refresh initializes the plugin index repository. When the index directory is empty, it clones the asdf-plugins repository via p.repo.Clone(p.url, ""); if the clone fails the error is wrapped as 'unable to initialize index'. It means the plugin index could not be fetched from the remote git URL.

Solutions

Verify network connectivity to the index host (e.g. git ls-remote <index-url>).
Configure git/HTTPS proxy settings if behind a corporate proxy (git config --global http.proxy ...).
Confirm the index URL in config is correct and reachable.
Ensure git is installed and on PATH, then retry Refresh.

Example fix

// before: clone fails behind proxy
git ls-remote https://github.com/asdf-vm/asdf-plugins.git
// after
git config --global http.proxy http://proxy.corp:8080
rm -rf "${ASDF_DATA_DIR:-$HOME/.asdf}/repository" && asdf plugin list all

Defensive patterns

Strategy: retry

Validate before calling

url := p.url // e.g. https://github.com/asdf-vm/asdf-plugins.git
if _, err := exec.LookPath("git"); err != nil {
    return fmt.Errorf("git required: %w", err)
}
if err := exec.Command("git", "ls-remote", url, "HEAD").Run(); err != nil {
    return fmt.Errorf("index remote unreachable: %w", err)
}

Try / catch

ok, err := idx.Refresh()
if err != nil && strings.Contains(err.Error(), "unable to initialize index") {
    time.Sleep(2 * time.Second) // transient network?
    ok, err = idx.Refresh()
}

Prevention

Configure git proxy settings before first asdf use in corporate networks.
Prime the index with a one-time clone during image builds (pre-bake).
Verify connectivity to github.com in CI before running asdf commands.
Keep git installed and updated.

When it happens

Trigger: Calling Refresh (directly or via Get/GetPluginSourceURL) when the index directory is empty and: there is no network connectivity; the remote URL is wrong or unreachable; git is missing; git authentication is required (behind a proxy) but not configured.

Common situations: First run of asdf on a fresh machine with no internet; corporate proxy/firewall blocking github.com; misconfigured ASDF config pointing at a dead index URL; DNS failures in containers.

Related errors

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

Appendix: source

Thrown at internal/pluginindex/pluginindex.go:82

// Refresh may update the plugin repo if it hasn't been updated in longer
// than updateDurationMinutes. If the plugin repo needs to be updated the
// repo will be invoked to perform the actual Git pull.
func (p PluginIndex) Refresh() (bool, error) {
	err := os.MkdirAll(p.directory, os.ModePerm)
	if err != nil {
		return false, err
	}

	files, err := os.ReadDir(p.directory)
	if err != nil {
		return false, err
	}

	if len(files) == 0 {
		// directory empty, clone down repo
		err := p.repo.Clone(p.url, "")
		if err != nil {
			return false, fmt.Errorf("unable to initialize index: %w", err)
		}

		return touchFS(p.directory)
	}

	// directory must not be empty, repo must be present, maybe update
	updated, err := lastUpdated(p.directory)
	if err != nil {
		return p.doUpdate()
	}

	// Convert minutes to nanoseconds
	updateDurationNs := int64(p.updateDurationMinutes) * (6e10)

	if updated > updateDurationNs && !p.disableUpdate {
		return p.doUpdate()
	}

View on GitHub (pinned to 074a1722ca)