{"record":{"id":"78e13812ea577271","repo":"thanos-io/thanos","slug":"the-ingester-max-global-series-per-user-limit-is-u","errorCode":null,"errorMessage":"The ingester.max-global-series-per-user limit is unsupported if distributor.shard-by-all-labels is disabled","messagePattern":"The ingester\\.max-global-series-per-user limit is unsupported if distributor\\.shard-by-all-labels is disabled","errorType":"validation","errorClass":"LimitError","httpStatus":null,"severity":"error","filePath":"internal/cortex/util/validation/limits.go","lineNumber":23,"sourceCode":"\nimport (\n\t\"bytes\"\n\t\"encoding/json\"\n\t\"errors\"\n\t\"flag\"\n\t\"maps\"\n\t\"math\"\n\t\"strings\"\n\t\"time\"\n\n\t\"github.com/prometheus/common/model\"\n\t\"github.com/prometheus/prometheus/model/relabel\"\n\t\"golang.org/x/time/rate\"\n\n\t\"github.com/thanos-io/thanos/internal/cortex/util/flagext\"\n)\n\nvar errMaxGlobalSeriesPerUserValidation = errors.New(\"The ingester.max-global-series-per-user limit is unsupported if distributor.shard-by-all-labels is disabled\")\n\n// Supported values for enum limits\nconst (\n\tLocalIngestionRateStrategy  = \"local\"\n\tGlobalIngestionRateStrategy = \"global\"\n)\n\n// LimitError are errors that do not comply with the limits specified.\ntype LimitError string\n\nfunc (e LimitError) Error() string {\n\treturn string(e)\n}\n\n// Limits describe all the limits for users; can be used to describe global default\n// limits via flags, or per-user limits via yaml config.\ntype Limits struct {\n\t// Distributor enforced limits.","sourceCodeStart":5,"sourceCodeEnd":41,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/internal/cortex/util/validation/limits.go#L5-L41","documentation":"errMaxGlobalSeriesPerUserValidation enforces a configuration invariant in Limits.Validate: MaxGlobalSeriesPerUser (ingester.max-global-series-per-user) is a per-cluster aggregate limit that only makes sense when series are consistently sharded across ingesters, i.e. when distributor.shard-by-all-labels is enabled. Setting a positive global limit with sharding disabled is rejected at startup.","triggerScenarios":"Limits.Validate is called (config load / startup) with ingester.max-global-series-per-user > 0 while distributor.shard-by-all-labels is false; also asserted in limits tests.","commonSituations":"Operator copies a config between Cortex/Thanos deployments and enables the global limit but forgets shard-by-all-labels; migration from old default (shard-by-all-labels=false) to newer configs that assume it is on.","solutions":["Set distributor.shard-by-all-labels: true in the config.","Or remove/zero ingester.max-global-series-per-user and rely on ingester.max-series-per-user (per-instance) limits instead.","Note the migration requirement: enabling shard-by-all-labels requires ingester ring resharding — plan a rollout per upstream docs.","Run config validation locally before deploy (Validate is invoked during flag parsing/config load) to catch the mismatch early."],"exampleFix":"// before (config)\ningester:\n  max-global-series-per-user: 100000\n# after (config)\ndistributor:\n  shard-by-all-labels: true\ningester:\n  max-global-series-per-user: 100000","handlingStrategy":"validation","validationCode":"if limits.MaxGlobalSeriesPerUser > 0 && !shardByAllLabels {\n    return errors.New(\"max-global-series-per-user requires shard-by-all-labels=true\")\n}\n// then call Limits.Validate(...)","typeGuard":null,"tryCatchPattern":"if err := limits.Validate(shardByAllLabels); err != nil {\n    return fmt.Errorf(\"invalid limits config: %w\", err)\n}","preventionTips":["Validate config in CI with Limits.Validate before deploy.","Pair any max-global-series-per-user setting with shard-by-all-labels: true.","Document the interdependency in your config templates.","Prefer per-instance limits if shard-by-all-labels cannot be enabled."],"tags":["config","validation","limits"],"backgroundTag":"conflicting-config-options","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"}