What causes "invalid OCI reference: %w" in helm/helm?

Use a fully qualified OCI reference with no scheme: registry.example.com/namespace/plugin:1.0.0

invalid OCI reference: %w

Error message

invalid OCI reference: %w

What it means

GetPluginName (pkg/registry/plugin.go) parses the source string with the OCI reference parser (newReference). If the string is not a well-formed registry/repository[:tag|@digest] reference, parsing fails and this error wraps the parser's specific reason.

Source

Thrown at pkg/registry/plugin.go:187

		withProv   bool
	}

	// PluginPullOption allows customizing plugin pull operations
	PluginPullOption func(*pluginPullOperation)
)

// PluginPullOptWithPluginName sets the plugin name for validation
func PluginPullOptWithPluginName(name string) PluginPullOption {
	return func(operation *pluginPullOperation) {
		operation.pluginName = name
	}
}

// GetPluginName extracts the plugin name from an OCI reference using proper reference parsing
func GetPluginName(source string) (string, error) {
	ref, err := newReference(source)
	if err != nil {
		return "", fmt.Errorf("invalid OCI reference: %w", err)
	}

	// Extract plugin name from the repository path
	// e.g., "ghcr.io/user/plugin-name:v1.0.0" -> Repository: "user/plugin-name"
	repository := ref.Repository
	if repository == "" {
		return "", errors.New("invalid OCI reference: missing repository")
	}

	// Get the last part of the repository path as the plugin name
	parts := strings.Split(repository, "/")
	pluginName := parts[len(parts)-1]

	if pluginName == "" {
		return "", fmt.Errorf("invalid OCI reference: cannot determine plugin name from repository %s", repository)
	}

	return pluginName, nil

View on GitHub (pinned to 2a29f1770b)

Solutions

Use a fully qualified OCI reference with no scheme: registry.example.com/namespace/plugin:1.0.0
Strip any oci:// prefix before passing the ref to registry package APIs
Quote refs in shell scripts to prevent word splitting and whitespace contamination
Read the wrapped error text - it states exactly which component of the reference is invalid

Example fix

// before
name, err := registry.GetPluginName("https://ghcr.io/user/my-plugin:1.0.0")

// after
ref := strings.TrimPrefix("oci://ghcr.io/user/my-plugin:1.0.0", "oci://")
name, err := registry.GetPluginName(ref)

Defensive patterns

Strategy: validation

Validate before calling

src := strings.TrimSpace(ref)
src = strings.TrimPrefix(src, "oci://")
if _, err := registry.ParseReference(src); err != nil { // github.com/oras-go/v2/registry
	return fmt.Errorf("invalid OCI reference %q: %w", ref, err)
}

Try / catch

name, err := registry.GetPluginName(source)
if err != nil {
	if strings.Contains(err.Error(), "invalid OCI reference") {
		// surface the ref format problem to the user/config layer
	}
	return err
}

Prevention

Normalize refs before use: trim whitespace and strip oci:// prefixes
Always use fully qualified refs (registry/repo:tag or @digest) built from constants, not string surgery
Validate refs with oras-go's registry.ParseReference at the config/CLI boundary

When it happens

Trigger: Calling GetPluginName, or `helm plugin install` from an oci:// source which derives the plugin name, with a malformed ref: missing registry host, a URL with a scheme like https://, whitespace, invalid tag characters, or a malformed digest reference.

Common situations: Passing https:// URLs where an OCI ref is expected; refs pasted with trailing whitespace or newlines; shell variables that are empty or still contain the oci:// prefix; invalid characters in the tag portion.

Related errors

AI-assisted analysis of helm/helm@2a29f1770b (2026-08-15). Data as JSON: /api/errors/9ec365543e123ad5. Report an issue: GitHub.