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: %w

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.

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)

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.