What causes "Short-name plugin repository is disabled" in asdf-vm/asdf?

Pass the full plugin repository URL explicitly: `asdf plugin add `, which bypasses the short-name index path

Short-name plugin repository is disabled

Error message

Short-name plugin repository is disabled

What it means

asdf's plugin Add supports adding plugins by short name, resolved via a remote plugin index (plugin repository). When the short-name repository is explicitly disabled in asdf config (DisablePluginShortNameRepository), Add cannot resolve a short name to a git URL, so it refuses with this error. It is a guard so users get a clear message instead of a confusing index lookup failure.

Source

Thrown at internal/plugins/plugins.go:383

	}

	exists, err := PluginExists(config.DataDir, pluginName)
	if err != nil {
		return fmt.Errorf("unable to check if plugin already exists: %w", err)
	}

	if exists {
		return NewPluginAlreadyExists(pluginName)
	}

	plugin := New(config, pluginName)

	if pluginURL == "" {
		// Ignore error here as the default value is fine
		disablePluginIndex, _ := config.DisablePluginShortNameRepository()

		if disablePluginIndex {
			return fmt.Errorf("Short-name plugin repository is disabled")
		}

		lastCheckDuration := 0
		// We don't care about errors here as we can use the default value
		checkDuration, _ := config.PluginRepositoryLastCheckDuration()

		if !checkDuration.Never {
			lastCheckDuration = checkDuration.Every
		}

		index := pluginindex.Build(config.DataDir, config.PluginIndexURL, false, lastCheckDuration)
		var err error
		pluginURL, err = index.GetPluginSourceURL(pluginName)
		if err != nil {
			return fmt.Errorf("error fetching plugin URL: %s", err)
		}
	}

View on GitHub (pinned to 074a1722ca)

Solutions

Pass the full plugin repository URL explicitly: `asdf plugin add <name> <git-url>`, which bypasses the short-name index path
Disable the short-name repository restriction by removing disable_plugin_short_name_repository = true from ~/.asdfrc or unsetting ASDF_DISABLE_PLUGIN_SHORT_NAME_REPOSITORY
Check the resolved config (asdf config) to confirm which setting disabled the repository

Example fix

// before
plugins.Add(conf, "nodejs", "", "", os.Stdout) // short name, index disabled
// after
plugins.Add(conf, "nodejs", "https://github.com/asdf-vm/asdf-nodejs.git", "", os.Stdout)

Defensive patterns

Strategy: validation

Validate before calling

disabled, _ := config.DisablePluginShortNameRepository()
if disabled && pluginURL == "" {
    return fmt.Errorf("short-name repo disabled; pass an explicit plugin URL")
}
err := plugins.Add(conf, name, pluginURL, ref, os.Stdout)

Try / catch

if err != nil && strings.Contains(err.Error(), "Short-name plugin repository is disabled") {
    // fall back to explicit URL
}

Prevention

Always pass an explicit git URL when the index may be disabled
Read ASDF_DISABLE_PLUGIN_SHORT_NAME_REPOSITORY / asdfrc before scripting short-name adds

When it happens

Trigger: Calling plugins.Add (or `asdf plugin add <name>` in the CLI) with an empty pluginURL while the config option disable_plugin_short_name_repository / ASDF_DISABLE_PLUGIN_SHORT_NAME_REPOSITORY is enabled.

Common situations: Users on locked-down/air-gapped machines or corporate setups who disabled the plugin index but still try `asdf plugin add nodejs` with a short name instead of a full git URL.

Related errors

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