{"record":{"id":"3b219b7a7a8a5826","repo":"thanos-io/thanos","slug":"failed-to-create-matchers-cache","errorCode":null,"errorMessage":"failed to create matchers cache","messagePattern":"failed to create matchers cache","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/thanos/receive.go","lineNumber":235,"sourceCode":"\t\t\treturn errors.Wrap(err, \"open storage dir\")\n\t\t}\n\n\t\t// Create TSDB for the default tenant.\n\t\tif err := createDefautTenantTSDB(logger, conf.defaultTenantID, dataDir); err != nil {\n\t\t\treturn errors.Wrapf(err, \"create default tenant tsdb in %v\", conf.dataDir)\n\t\t}\n\t}\n\n\trelabelConfig, err := conf.relabelCfg.RelabelConfig(nil)\n\tif err != nil {\n\t\treturn errors.Wrap(err, \"get relabel configuration\")\n\t}\n\n\tvar cache = storecache.NoopMatchersCache\n\tif conf.matcherCacheSize > 0 {\n\t\tcache, err = storecache.NewMatchersCache(storecache.WithSize(conf.matcherCacheSize), storecache.WithPromRegistry(reg))\n\t\tif err != nil {\n\t\t\treturn errors.Wrap(err, \"failed to create matchers cache\")\n\t\t}\n\t\tmultiTSDBOptions = append(multiTSDBOptions, receive.WithMatchersCache(cache))\n\t}\n\n\tmultiTSDBOptions = append(multiTSDBOptions, receive.WithUploadConcurrency(conf.uploadConcurrency))\n\n\tdbs := receive.NewMultiTSDB(\n\t\tdataDir,\n\t\tlogger,\n\t\treg,\n\t\ttsdbOpts,\n\t\tlset,\n\t\tconf.tenantLabelName,\n\t\tbkt,\n\t\tconf.allowOutOfOrderUpload,\n\t\tconf.skipCorruptedBlocks,\n\t\thashFunc,\n\t\tmultiTSDBOptions...,","sourceCodeStart":217,"sourceCodeEnd":253,"githubUrl":"https://github.com/thanos-io/thanos/blob/35b8b991177def87ed52dcf10f9b6d87f07282c8/cmd/thanos/receive.go#L217-L253","documentation":"runReceive tries to initialize a matchers cache for the store API via storecache.NewMatchersCache when --store.enable-thanos-compressed-response / matcher cache size is set (>0). The error wraps any failure from the cache constructor, most commonly a failure to register the cache's Prometheus metrics with the registry. Receive exits with this error during startup.","triggerScenarios":"Starting `thanos receive` with --matcher-cache-size greater than 0 while storecache.NewMatchersCache(WithSize(...), WithPromRegistry(...)) returns an error, e.g. metric registration fails against the provided Prometheus registerer.","commonSituations":"Passing a huge or negative-derived cache size configuration; a custom/limited Prometheus registry that rejects metric registration; corrupted or conflicting metric collectors already registered.","solutions":["Inspect the wrapped cause: enable debug logging and read the underlying error returned by storecache.NewMatchersCache.","Verify --matcher-cache-size is a sane positive integer (e.g. 10000) and not malformed.","Ensure the Prometheus registerer passed to runReceive is healthy and does not already have conflicting collectors registered.","Pin/upgrade Thanos to a version matching your Prometheus client_golang to avoid metric incompatibilities.","If you do not need caching, omit --matcher-cache-size so the NoopMatchersCache is used."],"exampleFix":"// before\nthanos receive --matcher-cache-size=0abc\n// after\nthanos receive --matcher-cache-size=10000","handlingStrategy":"validation","validationCode":"if size, err := strconv.Atoi(flagValue); err != nil || size <= 0 { return fmt.Errorf(\"--matcher-cache-size must be a positive integer, got %q\", flagValue) }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Validate flag values before launching receive","Keep Thanos and Prometheus client library versions aligned","Register cache metrics only once per registry","Omit matcher-cache-size if caching is not required"],"tags":["startup","prometheus","cache","configuration"],"backgroundTag":"invalid-config-value","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"}