cayleygraph/cayley · error

trying to add to map bucket %s with key 0

Error message

trying to add to map bucket %s with key 0

What it means

This error means addToMapBucket received a key whose second element (the in-bucket key) is empty. The map bucket needs a non-empty value key to store the uint64 ID under; an empty key signals an upstream value was not resolved before indexing.

Source

Thrown at graph/kv/indexing.go:960

				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
}

func (qs *QuadStore) flushMapBucket(ctx context.Context, tx kv.Tx) error {
	bs := make([]string, 0, len(qs.mapBucket))
	for k := range qs.mapBucket {

View on GitHub (pinned to 81dcd7d73e)

Solutions

1. Ensure the node value is resolved to a non-empty byte key (via the value-to-key encoding) before calling addToMapBucket.
2. Skip/defer indexing of values that cannot be encoded, and log them instead of indexing an empty key.
3. Check for nil quad.Value entries in incoming quads and reject or normalize them at write time.

Example fix

// before
k := valueKeyFor(v) // may return []byte{}
return qs.addToMapBucket(tx, kv.Key{bucket, k}, id)
// after
k := valueKeyFor(v)
if len(k) == 0 { return fmt.Errorf("cannot index value %v: empty key", v) }
return qs.addToMapBucket(tx, kv.Key{bucket, k}, id)

if v == nil || len(valueKeyFor(v)) == 0 { skip or normalize before indexing }

func hasEncodableKey(v quad.Value) bool { return v != nil && len(valueKeyFor(v)) > 0 }

err := qs.addToMapBucket(tx, key, id)
if err != nil { return fmt.Errorf("indexing value %d: %w", id, err) }

When it happens

Trigger: indexLink calls addToMapBucket with a key whose second component is a zero-length byte slice — typically when the node value could not be encoded to bytes (missing/nil value, failed quad.Value key derivation).

Common situations: Quads containing nil or unencodable node values, values not yet registered in the value map before indexing, or custom key-encoding functions returning empty bytes.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• no indexes defined
• trying to add to map bucket with invalid key: %v
• ErrNoBucket
• ErrEmptyPath
• kv: data version is out of date. Run cayleyupgrade for your

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