thanos-io/thanos · error

expected Alertmanager API version to be one of

Error message

expected Alertmanager API version to be one of %v but got %q

What it means

After decoding api_version as a string, UnmarshalYAML compares it against supportedAPIVersions; if no match, it errors with the list of accepted versions and the offending value. This rejects Alertmanager API versions this Thanos build does not support.

Solutions

1. Set api_version to one of the supported values listed in the error message (typically "api/v2"), or remove the field to accept the default.
2. If you need a newer API version, upgrade Thanos to a build whose supportedAPIVersions includes it.
3. Check case and spelling against the exact supported list.

Example fix

// before
api_version: v3
// after
api_version: "v2"

allowed := []APIVersion{"api/v2"} // mirror supportedAPIVersions
if !slices.Contains(allowed, APIVersion(cfg.APIVersion)) {
    return fmt.Errorf("api_version %q not in %v", cfg.APIVersion, allowed)
}

When it happens

Trigger: Setting api_version to any string not in supportedAPIVersions (e.g. api_version: v1 or api_version: v3) in AlertmanagerConfig YAML.

Common situations: Targeting an old Alertmanager with v1; using a newer API version (api_version: v3) than the embedded Thanos/prometheus/alertmanager client supports; typos like "V2" (case-sensitive).

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

• unsupported format for label
• --auto-gomemlimit.ratio must be greater than 0 and less…
• unable to unmarshal config content
• endpoint
• unable to validate endpoints

AI-assisted analysis of thanos-io/thanos@35b8b99117 (2026-09-07). Data as JSON: /api/errors/2ebb677cc5ccd644. Report an issue: GitHub.

Appendix: source

Thrown at pkg/alert/config.go:59

var supportedAPIVersions = []APIVersion{
	APIv1, APIv2,
}

// UnmarshalYAML implements the yaml.Unmarshaler interface.
func (v *APIVersion) UnmarshalYAML(unmarshal func(any) error) error {
	var s string
	if err := unmarshal(&s); err != nil {
		return errors.Wrap(err, "invalid Alertmanager API version")
	}

	for _, ver := range supportedAPIVersions {
		if APIVersion(s) == ver {
			*v = ver
			return nil
		}
	}
	return errors.Errorf("expected Alertmanager API version to be one of %v but got %q", supportedAPIVersions, s)
}

func DefaultAlertmanagerConfig() AlertmanagerConfig {
	return AlertmanagerConfig{
		EndpointsConfig: clientconfig.HTTPEndpointsConfig{
			Scheme:          "http",
			StaticAddresses: []string{},
			FileSDConfigs:   []clientconfig.HTTPFileSDConfig{},
		},
		Timeout:    model.Duration(time.Second * 10),
		APIVersion: APIv2,
	}
}

// UnmarshalYAML implements the yaml.Unmarshaler interface.
func (c *AlertmanagerConfig) UnmarshalYAML(unmarshal func(any) error) error {
	*c = DefaultAlertmanagerConfig()
	type plain AlertmanagerConfig

View on GitHub (pinned to 35b8b99117)