{"record":{"id":"ecde89c47918fa33","repo":"thanos-io/thanos","slug":"invalid-alertmanager-api-version","errorCode":null,"errorMessage":"invalid Alertmanager API version","messagePattern":"invalid Alertmanager API version","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/alert/config.go","lineNumber":50,"sourceCode":"}\n\n// APIVersion represents the API version of the Alertmanager endpoint.\ntype APIVersion string\n\nconst (\n\tAPIv1 APIVersion = \"v1\"\n\tAPIv2 APIVersion = \"v2\"\n)\n\nvar supportedAPIVersions = []APIVersion{\n\tAPIv1, APIv2,\n}\n\n// UnmarshalYAML implements the yaml.Unmarshaler interface.\nfunc (v *APIVersion) UnmarshalYAML(unmarshal func(any) error) error {\n\tvar s string\n\tif err := unmarshal(&s); err != nil {\n\t\treturn errors.Wrap(err, \"invalid Alertmanager API version\")\n\t}\n\n\tfor _, ver := range supportedAPIVersions {\n\t\tif APIVersion(s) == ver {\n\t\t\t*v = ver\n\t\t\treturn nil\n\t\t}\n\t}\n\treturn errors.Errorf(\"expected Alertmanager API version to be one of %v but got %q\", supportedAPIVersions, s)\n}\n\nfunc DefaultAlertmanagerConfig() AlertmanagerConfig {\n\treturn AlertmanagerConfig{\n\t\tEndpointsConfig: clientconfig.HTTPEndpointsConfig{\n\t\t\tScheme:          \"http\",\n\t\t\tStaticAddresses: []string{},\n\t\t\tFileSDConfigs:   []clientconfig.HTTPFileSDConfig{},\n\t\t},","sourceCodeStart":32,"sourceCodeEnd":68,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/pkg/alert/config.go#L32-L68","documentation":"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.","triggerScenarios":"UnmarshalYAML on AlertmanagerConfig where the 'api_version' YAML node is not a scalar string (nested object, array, or non-string scalar).","commonSituations":"Copy-pasted config where api_version is indented as a mapping; api_version: [v1]; quoting/typing mistakes like api_version: 1.","solutions":["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.","Validate the config with a strict YAML parse locally before deploying."],"exampleFix":"// before\nalertmanagers:\n  - api_version:\n      name: v2\n// after\nalertmanagers:\n  - api_version: \"v2\"","handlingStrategy":"validation","validationCode":"node, err := yaml.Unmarshal(rawCfg)\n// ensure api_version is a scalar string before feeding to AlertmanagerConfig\nif n, ok := node.Value; !ok || n == nil { return fmt.Errorf(\"api_version must be a plain scalar string\") }","typeGuard":"func isStringScalar(n *yaml.Node) bool { return n != nil && n.Kind == yaml.ScalarNode && n.Tag == \"!!str\" }","tryCatchPattern":null,"preventionTips":["Always write api_version as a quoted scalar in YAML","Run strict YAML linting on alertmanager config before deploy","Read the errors.Wrap cause to distinguish decode failures from value failures"],"tags":["yaml","config","alertmanager"],"backgroundTag":"yaml-parse-error","analyzedSha":"35b8b991177def87ed52dcf10f9b6d87f07282c8","analyzedAt":"2026-09-07T01:49:59.689Z","contentChangedAt":"2026-09-07T01:49:59.689Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}