thanos-io/thanos · error

invalid Alertmanager API version

Error message

invalid Alertmanager API version

What it means

pkg/alert wraps any YAML unmarshal failure of the APIVersion field with 'invalid Alertmanager API version', meaning the value could not even be decoded as a string (e.g. it was a map, list, or number). It is a decode-stage error, distinct from the supported-version check that follows.

Solutions

1. Inspect the YAML node at the api_version key and make it a plain scalar string (e.g. api_version: "v2"), and check the wrapped cause in errors.Wrap for the exact decode problem.
2. Validate the config with a strict YAML parse locally before deploying.

Example fix

// before
alertmanagers:
  - api_version:
      name: v2
// after
alertmanagers:
  - api_version: "v2"

node, err := yaml.Unmarshal(rawCfg)
// ensure api_version is a scalar string before feeding to AlertmanagerConfig
if n, ok := node.Value; !ok || n == nil { return fmt.Errorf("api_version must be a plain scalar string") }

func isStringScalar(n *yaml.Node) bool { return n != nil && n.Kind == yaml.ScalarNode && n.Tag == "!!str" }

When it happens

Trigger: UnmarshalYAML on AlertmanagerConfig where the 'api_version' YAML node is not a scalar string (nested object, array, or non-string scalar).

Common situations: Copy-pasted config where api_version is indented as a mapping; api_version: [v1]; quoting/typing mistakes like api_version: 1.

Related errors

• unable to unmarshal config content
• parsing downstream tripper config YAML file
• parsing downstream tripper TLS config YAML
• initializing the query range cache config
• initializing the labels cache config

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

Appendix: source

Thrown at pkg/alert/config.go:50

}

// APIVersion represents the API version of the Alertmanager endpoint.
type APIVersion string

const (
	APIv1 APIVersion = "v1"
	APIv2 APIVersion = "v2"
)

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{},
		},

View on GitHub (pinned to 35b8b99117)