helm/helm · error

unable to perform search against %q

Error message

unable to perform search against %q

What it means

Returned in searchHubOptions.run (pkg/cmd/search_hub.go:95) when the HTTP search call c.SearchWithContext fails after the client was created successfully. Note the design: the raw error is logged via slog at debug level and the user-visible error only names the endpoint - the real cause (timeout, non-200, DNS failure, context cancellation) is hidden unless --debug is enabled.

Source

Thrown at pkg/cmd/search_hub.go:95

	f.BoolVar(&o.listRepoURL, "list-repo-url", false, "print charts repository URL")
	f.BoolVar(&o.failOnNoResult, "fail-on-no-result", false, "search fails if no results are found")

	bindOutputFlag(cmd, &o.outputFormat)

	return cmd
}

func (o *searchHubOptions) run(ctx context.Context, out io.Writer, args []string) error {
	c, err := monocular.New(o.searchEndpoint)
	if err != nil {
		return fmt.Errorf("unable to create connection to %q: %w", o.searchEndpoint, err)
	}

	q := strings.Join(args, " ")
	results, err := c.SearchWithContext(ctx, q)
	if err != nil {
		slog.Debug("search failed", slog.Any("error", err))
		return fmt.Errorf("unable to perform search against %q", o.searchEndpoint)
	}

	return o.outputFormat.Write(out, newHubSearchWriter(results, o.searchEndpoint, o.maxColWidth, o.listRepoURL, o.failOnNoResult))
}

type hubChartRepo struct {
	URL  string `json:"url"`
	Name string `json:"name"`
}

type hubChartElement struct {
	URL         string       `json:"url"`
	Version     string       `json:"version"`
	AppVersion  string       `json:"app_version"`
	Description string       `json:"description"`
	Repository  hubChartRepo `json:"repository"`
}

View on GitHub (pinned to 2a29f1770b)

Solutions

1. Re-run with --debug (or HELM_DEBUG=1) to see the logged 'search failed' cause.
2. Retry after confirming basic connectivity: 'curl -sS <endpoint>' - many failures are transient.
3. If the hub is persistently blocked, fall back to 'helm search repo' with locally added repositories.

Example fix

# before
helm search hub wordpress        # Error: unable to perform search against "..."

# after
helm search hub wordpress --debug # slog line 'search failed' shows the real error

out, err := cmdExecution("helm", "search", "hub", term, "--debug")
if err != nil {
    if strings.Contains(out+err.Error(), "unable to perform search") {
        // transient network path: backoff and retry once or twice
        time.Sleep(2 * time.Second)
        out, err = cmdExecution("helm", "search", "hub", term, "--debug")
    }
    if err != nil { return fmt.Errorf("hub search failed: %w", err) }
}

When it happens

Trigger: The monocular endpoint returns 5xx, times out, or the request context is cancelled (e.g. Ctrl-C or a caller-side ctx deadline); transient network drops between the client and the hub; hub API format changes producing a decode error.

Common situations: Flaky CI networking; rate limiting or WAF blocks on the public hub; slow proxy chains exceeding the request timeout; scheduled hub downtime.

Related errors

• unable to create connection to %q: %w
• unable to write results: %w
• failed to fetch %s : %s
• extracting files from archive: %w
• failed to download plugin: %w

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