thanos-io/thanos · warning

ErrInvalidBucketCacheKeyVerb

ErrInvalidBucketCacheKeyVerb

Error message

key has invalid verb

What it means

ParseBucketCacheKey requires the first colon-separated field of a cache key to be a known VerbType (e.g. subrange). If the verb is not recognized by IsValidVerb, the key cannot be interpreted and ErrInvalidBucketCacheKeyVerb is returned.

Solutions

1. Check the key's verb against cachekey.IsValidVerb before parsing and skip unknown verbs.
2. Clear/regenerate cache entries produced by an incompatible Thanos version.
3. Align all store-gateway/query instances to the same version so verb sets match.
4. Fix the key producer to emit one of the supported verbs (e.g. subrange).

Example fix

// before
ck, err := cachekey.ParseBucketCacheKey(key)
// after
if !cachekey.IsValidVerb(cachekey.VerbType(strings.SplitN(key, ":", 2)[0])) {
    return nil, nil // skip unknown-verb cache entry
}
ck, err := cachekey.ParseBucketCacheKey(key)

verb := cachekey.VerbType(strings.SplitN(key, ":", 2)[0])
if !cachekey.IsValidVerb(verb) {
    return nil, fmt.Errorf("unknown verb %q", verb)
}

func hasKnownVerb(key string) bool {
    parts := strings.SplitN(key, ":", 2)
    return len(parts) == 2 && cachekey.IsValidVerb(cachekey.VerbType(parts[0]))
}

ck, err := cachekey.ParseBucketCacheKey(key)
if errors.Is(err, cachekey.ErrInvalidBucketCacheKeyVerb) {
    logger.Debug("unknown cache key verb, skipping", "key", key)
    continue
}

When it happens

Trigger: Calling ParseBucketCacheKey with a key whose first segment is not a registered verb, e.g. "random:name" (as in the unit test) or "get:obj" where "get" is not a valid VerbType.

Common situations: Forward/backward version mismatch: newer writer introduced a verb an older reader doesn't know; manual cache inspection tools constructing keys; typo'd verb in custom cache implementations.

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

• ErrInvalidBucketCacheKeyFormat
• invalid reload method
• ErrParseKeyInt
• errObjNotFound
• failed to get object attributes

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

Appendix: source

Thrown at pkg/store/cache/cachekey/cachekey.go:15

// Copyright (c) The Thanos Authors.
// Licensed under the Apache License 2.0.

package cachekey

import (
	"strconv"
	"strings"

	"github.com/pkg/errors"
)

var (
	ErrInvalidBucketCacheKeyFormat = errors.New("key has invalid format")
	ErrInvalidBucketCacheKeyVerb   = errors.New("key has invalid verb")
	ErrParseKeyInt                 = errors.New("failed to parse integer in key")
)

// VerbType is the type of operation whose result has been stored in the caching bucket's cache.
type VerbType string

const (
	ExistsVerb        VerbType = "exists"
	ContentVerb       VerbType = "content"
	IterVerb          VerbType = "iter"
	IterRecursiveVerb VerbType = "iter-recursive"
	AttributesVerb    VerbType = "attrs"
	SubrangeVerb      VerbType = "subrange"
)

type BucketCacheKey struct {
	Verb                    VerbType
	Name                    string

View on GitHub (pinned to 35b8b99117)