helm/helm · error

unable to create connection to %q: %w

Error message

unable to create connection to %q: %w

What it means

Thrown in searchHubOptions.run (pkg/cmd/search_hub.go:88) when monocular.New cannot initialize a client for the hub endpoint configured via --endpoint (default: the Helm Hub / Artifact Hub monocular instance). The monocular error is wrapped with %w and includes the endpoint URL, so a malformed URL or unreachable host shows up here before any search request is made.

Source

Thrown at pkg/cmd/search_hub.go:88

			return o.run(c.Context(), out, args)
		},
	}

	f := cmd.Flags()
	f.StringVar(&o.searchEndpoint, "endpoint", "https://hub.helm.sh", "Hub instance to query for charts")
	f.UintVar(&o.maxColWidth, "max-col-width", 50, "maximum column width for output table")
	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 {

View on GitHub (pinned to 2a29f1770b)

Solutions

1. Check the URL printed in the message; ensure it includes the scheme (https://) and is reachable: 'curl -sS <endpoint>'.
2. If the default endpoint is blocked, verify network/proxy settings or point --endpoint at an accessible Monocular-compatible service.
3. For air-gapped use, prefer 'helm search repo' against locally added repositories instead of hub search.

Example fix

# before
helm search hub --endpoint hub.internal wordpress   # endpoint wrong/unreachable

# after
curl -sS https://hub.internal/v1/charts   # verify first
helm search hub --endpoint https://hub.internal wordpress

# bash: sanity-check a custom hub endpoint before searching
endpoint="https://hub.internal"
curl -fsS -o /dev/null "$endpoint" || { echo "hub endpoint unreachable" >&2; exit 1; }
helm search hub --endpoint "$endpoint" wordpress

When it happens

Trigger: Running 'helm search hub --endpoint <url> term' where the URL is malformed, uses an unsupported scheme, or the host cannot be resolved/connected; pointing --endpoint at a Monocular instance that is down.

Common situations: Private/air-gapped environments overriding the default hub endpoint; typos in --endpoint (missing scheme, trailing garbage); corporate proxies blocking the default hub host; on-prem Monocular behind maintenance.

Related errors

• unable to perform search against %q
• failed to fetch %s : %s
• unable to write results: %w
• 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/dcad397b04d5245c. Report an issue: GitHub.