juicedata/juicefs · error

invalid value for delayed slices %q: %v

Error message

invalid value for delayed slices %q: %v

What it means

kvMeta.deleteSustained (delayed-slice reference counting) decodes a 'delayed slices' metadata record with decodeDelayedSlices; the decode produced zero slices even though the raw buffer was non-empty, meaning the stored value is corrupt or written by an incompatible format. The client refuses to proceed rather than decrementing slice refcounts against garbage data.

Source

Thrown at pkg/meta/tkv.go:3087

			return nil
		}, 0); err != nil {
			logger.Warnf("Scan delayed slices: %s", err)
			return count, err
		}

		for _, key := range keys {
			if ctx.Canceled() {
				return count, ctx.Err()
			}
			if err := m.txn(ctx, func(tx *kvTxn) error {
				ss, rs = ss[:0], rs[:0]
				buf := tx.get(key)
				if len(buf) == 0 {
					return nil
				}
				m.decodeDelayedSlices(buf, &ss)
				if len(ss) == 0 {
					return fmt.Errorf("invalid value for delayed slices %q: %v", key, buf)
				}
				for _, s := range ss {
					rs = append(rs, tx.incrBy(m.sliceKey(s.Id, s.Size), -1))
				}
				tx.delete(key)
				b := utils.ReadBuffer(key[1:])
				ts := int64(b.Get64())
				id := b.Get64()
				m.genLog(tx, time.Now(), "CLEANUP_DELAYED_SLICES(%d,%d)", id, ts)
				return nil
			}); err != nil {
				logger.Warnf("Cleanup delayed slices %q: %s", key, err)
				continue
			}
			for i, s := range ss {
				if rs[i] < 0 {
					m.deleteSlice(s.Id, s.Size)
					count++

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Verify all clients use the same JuiceFS version (check MinClientVersion compatibility; upgrade/downgrade to match the version that wrote the record)
2. Dump the offending key ('S'-prefixed delayed slice key) and inspect the raw bytes; if corrupt, restore metadata from a known-good backup (juicefs dump/load)
3. Run 'juicefs fsck' against the volume to detect and repair inconsistent metadata
4. If the key is genuinely orphaned garbage, delete the specific key directly in the KV store after backing it up

Example fix

// before (corrupt record blocks gc entirely)
m.decodeDelayedSlices(buf, &ss)
if len(ss) == 0 {
	return fmt.Errorf("invalid value for delayed slices %q: %v", key, buf)
}
// after (operational workaround: skip and log the bad key)
m.decodeDelayedSlices(buf, &ss)
if len(ss) == 0 {
	logger.Warnf("skip corrupt delayed slices %q: %v", key, buf)
	return nil
}

// before gc/fsck, verify metadata consistency
out, _ := exec.Command("juicefs", "fsck", metaURL).CombinedOutput()
if strings.Contains(string(out), "corrupt") { /* repair or restore before gc */ }

if err := runGc(); err != nil {
	if strings.Contains(err.Error(), "invalid value for delayed slices") {
		// restore metadata from backup, then retry
	}
}

When it happens

Trigger: Running the 'gc' or 'fsck' style sweep (deleteSustained/delSustained path) over a TKV (TiKV/etcd/Badger/FDB) metadata engine whose DELAYED_SLICE ('S' prefix) record bytes are corrupt, truncated, or written by a different JuiceFS version with a different serialization.

Common situations: Metadata engine data partially restored from a backup or dump/load migration; concurrent writes from mixed JuiceFS client versions; disk-level corruption in a KV 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 key %x
• The entry of the root inode was not found
• unknown message type %d
• json: %s
• existing format is broken: %s

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