thanos-io/thanos · warning

ErrInvalidBucketCacheKeyFormat

ErrInvalidBucketCacheKeyFormat

Error message

key has invalid format

What it means

ParseBucketCacheKey splits a cache key on ':' and requires at least two parts (verb and name). If the key has fewer than two colon-separated fields, it cannot represent a cached bucket operation and ErrInvalidBucketCacheKeyFormat is returned. This indicates a malformed cache entry key, usually produced by a different version of the key format.

Solutions

1. Clear the bucket cache so all keys are regenerated in the current format.
2. Verify the cache key producer uses the current VerbType:name[:start:end] format.
3. Check for mixed Thanos versions sharing one cache backend and align them.
4. If parsing user input, validate the key contains at least one ':' before calling ParseBucketCacheKey.

Example fix

// before
ck, err := cachekey.ParseBucketCacheKey("randomname")
// after
if !strings.Contains(key, ":") {
    return fmt.Errorf("skipping malformed cache key %q", key)
}
ck, err := cachekey.ParseBucketCacheKey(key)

if !strings.Contains(key, ":") {
    return nil, fmt.Errorf("skip malformed cache key %q", key)
}

func looksLikeCacheKey(key string) bool {
    return strings.Count(key, ":") >= 1
}

ck, err := cachekey.ParseBucketCacheKey(key)
if err != nil {
    if errors.Is(err, cachekey.ErrInvalidBucketCacheKeyFormat) {
        continue // skip malformed entry
    }
    return err
}

When it happens

Trigger: Calling ParseBucketCacheKey with a key string containing no ':' (strings.Split yields len(slice) < 2), e.g. "randomname" instead of "subrange:name:start:end".

Common situations: Stale or hand-crafted cache entries left over from an older Thanos version that used a different key format; external tools writing cache keys; corrupted cache backends (e.g. memcached/in-memory cache seeded with wrong keys).

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• ErrInvalidBucketCacheKeyVerb
• ErrParseKeyInt
• errObjNotFound
• failed to get object attributes
• fetching range [ , ]: caching key for offset not found

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

Appendix: source

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

// 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

View on GitHub (pinned to 35b8b99117)