What causes "empty hostname-override is invalid" in kubernetes/kubernetes?

Set --hostname-override to a real, trimmed node name (lowercased automatically).

empty hostname-override is invalid

Error message

empty hostname-override is invalid

What it means

processHostnameOverrideFlag trims the --hostname-override flag value; if the original was non-empty but reduces to empty after TrimSpace (i.e. only whitespace), it returns 'empty hostname-override is invalid' (options.go:328). An all-whitespace value is meaningless for a node name and is rejected explicitly.

Source

Thrown at cmd/kube-proxy/app/options.go:328

	if ent.Has(fsnotify.Write) || ent.Has(fsnotify.Rename) {
		// error out when ConfigFile is updated
		o.errCh <- fmt.Errorf("content of the proxy server's configuration file was updated")
		return
	}
	o.errCh <- nil
}

func (o *Options) errorHandler(err error) {
	o.errCh <- err
}

// processHostnameOverrideFlag processes hostname-override flag
func (o *Options) processHostnameOverrideFlag() error {
	// Check if hostname-override flag is set and use value since configFile always overrides
	if len(o.hostnameOverride) > 0 {
		hostName := strings.TrimSpace(o.hostnameOverride)
		if len(hostName) == 0 {
			return fmt.Errorf("empty hostname-override is invalid")
		}
		o.config.HostnameOverride = strings.ToLower(hostName)
	}

	return nil
}

// processV1Alpha1Flags processes v1alpha1 flags which can't be directly mapped to internal config.
func (o *Options) processV1Alpha1Flags(fs *pflag.FlagSet) {
	if fs.Changed("iptables-sync-period") && o.config.Mode != kubeproxyconfig.ProxyModeIPVS {
		o.config.SyncPeriod.Duration = o.iptablesSyncPeriod
	}
	if fs.Changed("iptables-min-sync-period") && o.config.Mode != kubeproxyconfig.ProxyModeIPVS {
		o.config.MinSyncPeriod.Duration = o.iptablesMinSyncPeriod
	}
	if fs.Changed("ipvs-sync-period") && o.config.Mode == kubeproxyconfig.ProxyModeIPVS {
		o.config.SyncPeriod.Duration = o.ipvsSyncPeriod
	}

View on GitHub (pinned to b882c60b40)

Solutions

Set --hostname-override to a real, trimmed node name (lowercased automatically).
If you do not need an override, omit the flag entirely.
Fix the templating/env source so it does not emit whitespace.
Restart kube-proxy.

Example fix

// before
// --hostname-override="   "
// after
// --hostname-override=node-1   (or omit the flag)

Defensive patterns

Strategy: validation

Validate before calling

// Trim and reject whitespace-only hostname overrides before launch.
func validateHostnameOverride(h string) error {
    if len(h) == 0 {
        return nil // flag omitted is valid
    }
    if len(strings.TrimSpace(h)) == 0 {
        return fmt.Errorf("empty hostname-override is invalid")
    }
    return nil
}

Prevention

Render --hostname-override only when the node-name variable is set in templates.
Omit the flag entirely if you rely on the node's actual hostname.
Lint rendered manifests for whitespace-only values.

When it happens

Trigger: Launching kube-proxy with --hostname-override=" " or --hostname-override="\t", or a chart/helm template rendering a blank variable into that flag (e.g. {{ .Values.nodeName }} when unset yields spaces).

Common situations: Helm/templating emits spaces for an unset node name; an env var expanded to whitespace; a copy-paste from YAML where indentation introduced stray spaces.

Related errors

AI-assisted analysis of kubernetes/kubernetes@b882c60b40 (2026-08-07). Data as JSON: /api/errors/a66e61dd5f5781d6. Report an issue: GitHub.