What causes "get prefix %v with count only: %s" in juicedata/juicefs?

Check etcd endpoint health and client log for the wrapped gRPC error

get prefix %v with count only: %s

Error message

get prefix %v with count only: %s

What it means

`etcdTxn.exist` checks whether any key exists under a prefix using an etcd Get with `WithPrefix` and `WithCountOnly`. A transport/etcd error on that count query panics with this message. Unlike plain `exist` used inside transactions, this is the count-only existence probe.

Source

Thrown at pkg/meta/tkv_etcd.go:130

	if keysOnly {
		opts = append(opts, etcd.WithKeysOnly())
	}
	resp, err := tx.kv.Get(tx.ctx, string(begin), opts...)
	if err != nil {
		panic(fmt.Errorf("get range [%v-%v): %s", string(begin), string(end), err))
	}
	for _, kv := range resp.Kvs {
		tx.observed[string(kv.Key)] = kv.ModRevision
		if !handler(kv.Key, kv.Value) {
			break
		}
	}
}

func (tx *etcdTxn) exist(prefix []byte) bool {
	resp, err := tx.kv.Get(tx.ctx, string(prefix), etcd.WithPrefix(), etcd.WithCountOnly())
	if err != nil {
		panic(fmt.Errorf("get prefix %v with count only: %s", string(prefix), err))
	}
	return resp.Count > 0
}

func (tx *etcdTxn) set(key, value []byte) {
	tx.buffer[string(key)] = value
	if len(tx.buffer) >= 128 {
		err := tx.commmit()
		if err != nil {
			panic(err)
		}
		tx.observed = make(map[string]int64)
		tx.buffer = make(map[string][]byte)
	}
}

func (tx *etcdTxn) append(key []byte, value []byte) {
	new := append(tx.get(key), value...)

View on GitHub (pinned to c9a67b23e8)

Solutions

Check etcd endpoint health and client log for the wrapped gRPC error
Correct endpoint/TLS/credentials in the metadata URL
Retry once etcd is reachable; tune timeouts if deadline errors recur

Defensive patterns

Strategy: retry

Validate before calling

etcdctl --endpoints=host:2379 get /your-prefix --prefix --count-only

Try / catch

if err := mountCmd.Run(); err != nil {
    if strings.Contains(err.Error(), "count only") { healthCheckEtcd(); retry(mountCmd) }
}

Prevention

Pre-check etcd health before mounts/loads
Verify TLS and auth parameters in the metadata URL
Alert on etcd downtime to correlate with client errors

When it happens

Trigger: Any existence check against a key prefix when the count-only Get fails: etcd unreachable, gRPC timeout, auth failure, or server error during the request.

Common situations: etcd down or restarting; credentials misconfigured; network partition; context deadline exceeded under cluster load — typically encountered at startup or when checking max slice/session keys.

Understand the failure class

Background: Database query failed: Internal Server Error 500s wrapping SQL, Prisma, and connection failures — what to check first — this error's family across 16 libraries.

Related errors

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