juicedata/juicefs · error

expect 1 keys but got %d

Error message

expect 1 keys but got %d

What it means

`etcdTxn.get` requests a key with `WithLimit(1)` and a range, then asserts it receives at most 1 KV. If etcd returns more than one pair for a point-style lookup (an internal invariant), the code panics: 'expect 1 keys but got N'. This guards against misuse of the Get options that would return multiple keys.

Source

Thrown at pkg/meta/tkv_etcd.go:58

	observed map[string]int64
	buffer   map[string][]byte
}

func (tx *etcdTxn) get(key []byte) []byte {
	k := string(key)
	if v, ok := tx.buffer[k]; ok {
		return v
	}
	resp, err := tx.kv.Get(tx.ctx, k, etcd.WithLimit(1))
	if err != nil {
		panic(fmt.Errorf("get %v: %s", k, err))
	}
	if resp.Count == 0 {
		tx.observed[k] = 0
		return nil
	}
	if resp.Count > 1 {
		panic(fmt.Errorf("expect 1 keys but got %d", resp.Count))
	}
	for _, pair := range resp.Kvs {
		if bytes.Equal(pair.Key, key) {
			tx.observed[k] = pair.ModRevision
			return pair.Value
		} else {
			panic(fmt.Errorf("expect key %v, but got %v", k, string(pair.Key)))
		}
	}
	panic("unreachable")
}

func (tx *etcdTxn) gets(keys ...[]byte) [][]byte {
	if len(keys) > 128 {
		var rs = make([][]byte, 0, len(keys))
		for i := 0; i < len(keys); i += 128 {
			rs = append(rs, tx.gets(keys[i:min(i+128, len(keys))]...)...)
		}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Reproduce with logging on the exact key requested; confirm whether a range rather than exact key is being fetched
2. Upgrade JuiceFS to the latest release and etcd server to a supported version
3. File an issue with the JuiceFS maintainers including the etcd version and the key pattern if it reproduces

// This panic indicates an internal invariant; capture stack and version info
if strings.Contains(err.Error(), "expect 1 keys but got") {
    log.Fatalf("etcd txn invariant violated, report issue with stack: %v", err)
}

When it happens

Trigger: An etcd Get issued for a single key unexpectedly returns multiple KVs — essentially only possible if the lookup is constructed as a range covering several keys, or etcd behaves unexpectedly.

Common situations: Corrupted or modified transaction code where the key argument is a prefix/range; a bug in etcd server or a proxy (e.g. gRPC gateway) mis-handling WithLimit; extremely rare, indicates an internal invariant violation rather than user error.

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

• expect key %v, but got %v
• get %v: %s
• database %s://%s is not empty
• batch get with %d keys: %s
• get range [%v-%v): %s

AI-assisted analysis of juicedata/juicefs@c9a67b23e8 (2026-09-06). Data as JSON: /api/errors/c49304b246716851. Report an issue: GitHub.