juicedata/juicefs · error

invalid sustainedKey: %s

Error message

invalid sustainedKey: %s

What it means

When dumping session info (dumpSessions), kvMeta parses sustained ('SS' prefixed) keys as 2-byte prefix + 16 bytes (8-byte session id + 8-byte inode). A key whose remaining buffer is not exactly 16 bytes is malformed and aborts the dump with this error.

Source

Thrown at pkg/meta/tkv.go:4129

	if err != nil {
		return err
	}
	cs := make([]int64, len(rs))
	for i, r := range rs {
		if r != nil {
			cs[i] = parseCounter(r)
		}
	}

	vals, err = m.scanValues(ctx, m.fmtKey("SS"), -1, nil)
	if err != nil {
		return err
	}
	ss := make(map[uint64][]Ino)
	for k := range vals {
		b := utils.FromBuffer([]byte(k[2:])) // "SS"
		if b.Len() != 16 {
			return fmt.Errorf("invalid sustainedKey: %s", k)
		}
		sid := b.Get64()
		inode := m.decodeInode(b.Get(8))
		ss[sid] = append(ss[sid], inode)
	}
	sessions := make([]*DumpedSustained, 0, len(ss))
	for k, v := range ss {
		sessions = append(sessions, &DumpedSustained{k, v})
	}

	// Fetch dir quotas
	pairs, err := m.scanValues(ctx, m.fmtKey("QD"), -1, func(k, v []byte) bool {
		return len(k) == 10 && len(v) == 32
	})
	if err != nil {
		return err
	}
	dirQuotas := make(map[Ino]*DumpedQuota, len(pairs))

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Inspect and remove/repair malformed 'SS'-prefixed keys in the metadata store
2. Restore metadata from a consistent 'juicefs dump' backup
3. Ensure the KV namespace is not shared with other applications
4. Clear stale sessions with 'juicefs status'/'--kill-session' style flows and let clients re-create them

Example fix

// before
b := utils.FromBuffer([]byte(k[2:]))
if b.Len() != 16 {
	return fmt.Errorf("invalid sustainedKey: %s", k)
}
// after (skip bad keys during dump)
b := utils.FromBuffer([]byte(k[2:]))
if b.Len() != 16 {
	logger.Warnf("skip invalid sustainedKey: %s", k)
	continue
}

// before dump, ensure metadata is consistent
juicefs fsck <meta-url>

if err := dumpMeta(url, out); err != nil {
	if strings.Contains(err.Error(), "invalid sustainedKey") {
		// inspect SS-prefix keys; clean stale sessions or restore backup
	}
}

When it happens

Trigger: Running 'juicefs dump' (or session listing) on a TKV engine whose 'SS' key space contains a truncated or foreign key — partial restore, manual KV edits, cross-version key encoding.

Common situations: Restored metadata from an incomplete backup; another application sharing the KV namespace; corrupted key bytes in the store.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• invalid value for delayed slices %q: %v
• invalid key %x
• invalid quota value: %v
• invalid dumped meta: missing 'Counters'
• The entry of the root inode was not found

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