GoogleContainerTools/skaffold · error

StatusCode_DEPLOY_HELM_USER_ERR

StatusCode_DEPLOY_HELM_USER_ERR

Error message

errors.Wrap(err, prefix)

What it means

helm.UserErr wraps helm-related failures attributable to the user's configuration or inputs with status code DEPLOY_HELM_USER_ERR. It is used broadly across the helm deployer (Dependencies, deployRelease, templateArgs, generateHelmManifest, generateSkaffoldOverrides) wherever a user-facing mistake causes the helm operation to fail.

Source

Thrown at pkg/skaffold/helm/errors.go:72

	return sErrors.NewErrorWithStatusCode(
		&proto.ActionableErr{
			Message: fmt.Sprintf("skaffold requires Helm version %s or greater", minVer),
			ErrCode: proto.StatusCode_DEPLOY_HELM_MIN_VERSION_ERR,
			Suggestions: []*proto.Suggestion{
				{
					SuggestionCode: proto.SuggestionCode_UPGRADE_HELM,
					Action:         fmt.Sprintf("Please upgrade helm to %s or higher via %s", minVer, installLink),
				},
			},
		})
}

func PluginErr(prefix string, err error) error {
	return deployerr.UserError(errors.Wrap(err, prefix), proto.StatusCode_RENDER_HELM_PLUGIN_ERR)
}

func UserErr(prefix string, err error) error {
	return deployerr.UserError(errors.Wrap(err, prefix), proto.StatusCode_DEPLOY_HELM_USER_ERR)
}

func CreateNamespaceErr(version string) error {
	return sErrors.NewErrorWithStatusCode(
		&proto.ActionableErr{
			Message: fmt.Sprintf("Skaffold config options `createNamespace` is not available in the current Helm version %s", version),
			ErrCode: proto.StatusCode_DEPLOY_HELM_CREATE_NS_NOT_AVAILABLE,
			Suggestions: []*proto.Suggestion{
				{
					SuggestionCode: proto.SuggestionCode_UPGRADE_HELM32,
					Action:         "\nPlease update Helm to version 3.2 or higher",
				},
				{
					SuggestionCode: proto.SuggestionCode_FIX_SKAFFOLD_CONFIG_HELM_CREATE_NAMESPACE,
					Action:         "set `releases.createNamespace` to false and try again",
				},
			},
		})

View on GitHub (pinned to a1189de023)

Solutions

1. Read the wrapped message — skaffold prefixes it with the failing operation (templateArgs, generateHelmManifest, etc.)
2. Validate the chart: `helm lint <chart-path>` and `helm template <release> <chart-path> -f <values>`
3. Fix skaffold.yaml: verify helmChart path, valuesFiles existence, and release/namespace names (lowercase alphanumeric and `-`)
4. Reproduce the exact helm command with -vdebug output (`skaffold deploy -vdebug`) and run it manually
5. Quote/escape special characters (commas, braces) in `set` values

Example fix

// before (skaffold.yaml)
helm:
  releases:
    - name: My.Release
      chartPath: ./charts/app
// after
helm:
  releases:
    - name: my-release
      chartPath: ./charts/app

func validateHelmRelease(r skaffoldHelmRelease) error {
  if r.ChartPath == "" { return fmt.Errorf("helmChart path is required") }
  if _, err := os.Stat(r.ChartPath); err != nil { return fmt.Errorf("chart not found at %s", r.ChartPath) }
  var releaseNameRe = regexp.MustCompile(`^[a-z0-9]([-a-z0-9]*[a-z0-9])?$`)
  if !releaseNameRe.MatchString(r.Name) { return fmt.Errorf("invalid release name %q", r.Name) }
  for _, vf := range r.ValuesFiles { if _, err := os.Stat(vf); err != nil { return fmt.Errorf("values file missing: %s", vf) } }
  return nil
}

null

if err := deploy(ctx); err != nil {
  var uerr *deployerr.UserError
  if errors.As(err, &uerr) && uerr.Code == proto.StatusCode_DEPLOY_HELM_USER_ERR {
    return fmt.Errorf("helm config problem (check chart path/values/release name): %w", errors.Unwrap(err))
  }
  return err
}

When it happens

Trigger: UserErr(prefix, err) fires when helm operations driven by user config fail: missing/invalid chart path, bad valuesFiles, invalid templated --set values, malformed generated manifest, failed dependencies build, or bad overrides JSON.

Common situations: Typo in `helmChart` path in skaffold.yaml; values file paths wrong or templating variables undefined; `releases[].set` values with unescaped commas; chart requiring a helm feature of a newer version; invalid namespace/release name characters.

Related errors

• strings.Join(errMsgs, "\n") (joined helm cleanup error messa
• could not prepare `skaffold filter`: %w
• StatusCode_DEPLOY_HELM_VERSION_ERR
• value must be one of `always`, `missing`, or `never`
• CONFIG_REMOTE_REPO_CACHE_NOT_FOUND_ERR

AI-assisted analysis of GoogleContainerTools/skaffold@a1189de023 (2026-09-05). Data as JSON: /api/errors/05253e12b82f27d9. Report an issue: GitHub.