What causes "unknown handling name %s" in vitessio/vitess?

Check the value in your config file/flag and correct the spelling to one of the names registered in handlingNamesToValues (see the String/Set code in go/viperutil/config.go for the accepted list).

vitessio/vitess · error

unknown handling name %s

Error message

unknown handling name %s

What it means

This error is returned by (*ConfigFileNotFoundHandling).Set in go/viperutil when a caller supplies a string that is not a recognized name for how to handle a missing config file. The Set method looks the lowercased argument up in handlingNamesToValues; if the key is absent, it rejects the value with this error. It exists to keep the handling enum closed — only documented names (e.g. the registered handling names) are accepted.

Source

Thrown at go/viperutil/config.go:293

	handlingNames = make([]string, 0, len(handlingNamesToValues))
	handlingValuesToNames = make(map[int]string, len(handlingNamesToValues))

	for name, val := range handlingNamesToValues {
		handlingValuesToNames[val] = name
		handlingNames = append(handlingNames, name)
	}

	slices.Sort(handlingNames)
}

func (h *ConfigFileNotFoundHandling) Set(arg string) error {
	larg := strings.ToLower(arg)
	if v, ok := handlingNamesToValues[larg]; ok {
		*h = ConfigFileNotFoundHandling(v)
		return nil
	}

	return fmt.Errorf("unknown handling name %s", arg)
}

func (h *ConfigFileNotFoundHandling) String() string {
	if name, ok := handlingValuesToNames[int(*h)]; ok {
		return name
	}

	return "<UNKNOWN>"
}

func (h *ConfigFileNotFoundHandling) Type() string { return "ConfigFileNotFoundHandling" }

View on GitHub (pinned to 01a25a7d17)

Solutions

Check the value in your config file/flag and correct the spelling to one of the names registered in handlingNamesToValues (see the String/Set code in go/viperutil/config.go for the accepted list).
Consult the docs or `--help` output for the valid ConfigFileNotFoundHandling options in your Vitess version.
If a new handling mode is genuinely needed, add a mapping to handlingNamesToValues and the corresponding handlingValuesToNames entry rather than passing an arbitrary string.

Example fix

// before (config.yaml)
config_file_not_found: StopOnMissing
// after
config_file_not_found: stop

Defensive patterns

Strategy: validation

Validate before calling

validHandlingNames := []string{"ignore", "warn", "error"} // check handlingNamesToValues in go/viperutil/config.go
if !slices.Contains(validHandlingNames, strings.ToLower(val)) {
	return fmt.Errorf("%q is not a valid ConfigFileNotFoundHandling name; expected one of %v", val, validHandlingNames)
}

Prevention

Keep handling values in one place (a config struct), never hardcoded strings scattered in configs.
Validate config at startup with a schema/enum check before viper decodes it.
Copy option names from the version's documentation, not from memory or other versions.

When it happens

Trigger: Calling Set (directly or via viper/decoder wiring in decodeHandlingValue) with a misspelled or unsupported string such as "Stop" vs "stop", "ingore", "fail", or an entirely invented mode name.

Common situations: Typos in config files or flag/env values for ConfigFileNotFoundHandling; users copying an option name from an older or newer Vitess version where the accepted names differ; case-sensitivity confusion (input is lowercased, so case is fine — the spelling is the problem).

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

AI-assisted analysis of vitessio/vitess@01a25a7d17 (2026-09-01). Data as JSON: /api/errors/dd0f8340003f2dbf. Report an issue: GitHub.