What causes "trying to add to map bucket with invalid key: %v" in cayleygraph/cayley?

Inspect the caller (indexLink) and ensure it always builds the key as kv.Key{bucket, valueKey} with exactly 2 elements.

trying to add to map bucket with invalid key: %v

Error message

trying to add to map bucket with invalid key: %v

What it means

This error means addToMapBucket was called with a key that does not have exactly two elements (bucket name + in-bucket key). The KV index writer requires a 2-part kv.Key to locate the map bucket; any other length indicates a caller bug in index construction.

Source

Thrown at graph/kv/indexing.go:956

				boff++
				continue
			}
			if x < b[boff] {
				break
			}
			if x == b[boff] {
				c = append(c, x)
				boff++
				break
			}
		}
	}
	return c
}

func (qs *QuadStore) addToMapBucket(tx kv.Tx, key kv.Key, value uint64) error {
	if len(key) != 2 {
		return fmt.Errorf("trying to add to map bucket with invalid key: %v", key)
	}
	b, k := key[0], key[1]
	if len(k) == 0 {
		return fmt.Errorf("trying to add to map bucket %s with key 0", b)
	}
	if qs.mapBucket == nil {
		qs.mapBucket = make(map[string]map[string][]uint64)
	}
	bucket := string(b)
	m, ok := qs.mapBucket[bucket]
	if !ok {
		m = make(map[string][]uint64)
		qs.mapBucket[bucket] = m
	}
	m[string(k)] = append(m[string(k)], value)
	mIndexWriteBufferEntries.WithLabelValues(bucket).Inc()
	return nil
}

View on GitHub (pinned to 81dcd7d73e)

Solutions

Inspect the caller (indexLink) and ensure it always builds the key as kv.Key{bucket, valueKey} with exactly 2 elements.
Verify any custom index definitions produce a bucket prefix plus a non-empty value key.
Re-run against upstream cayley code; this is an internal invariant, so update patched code if it diverges.

Example fix

// before
key := kv.Key{qs.indexBucket(dirs)}
return qs.addToMapBucket(tx, key, id)
// after
key := kv.Key{qs.indexBucket(dirs), valueKey}
return qs.addToMapBucket(tx, key, id)

Defensive patterns

Strategy: validation

Validate before calling

func validMapKey(key kv.Key) bool { return len(key) == 2 && len(key[1]) > 0 }
if !validMapKey(key) { return fmt.Errorf("bad map bucket key: %v", key) }

Type guard

func isTwoPartKey(k kv.Key) bool { return len(k) == 2 }

Prevention

Always build index keys via a single helper that returns kv.Key{bucket, valueKey}.
Add a unit test asserting key arity for every index definition.
Treat addToMapBucket errors during indexing as fatal bugs, not recoverable conditions.

When it happens

Trigger: indexLink builds a malformed 2-level key (e.g. appending only the bucket prefix without the value key, or concatenating parts into a single-element key) and calls qs.addToMapBucket(tx, key, value).

Common situations: Custom or patched index definitions in the KV quadstore, refactors of indexLink/key-building helpers that changed the key arity, or swapping backends where key layouts differ.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

AI-assisted analysis of cayleygraph/cayley@81dcd7d73e (2026-09-06). Data as JSON: /api/errors/69bdd91793d51ba9. Report an issue: GitHub.