juicedata/juicefs · error

invalid key %x

Error message

invalid key %x

What it means

During a full scan of the 'D' (deleted-file/trash size) key space, kvMeta expects every key to be exactly 17 bytes (1-byte prefix + 8-byte inode + 8-byte size). A key of any other length is treated as corrupt and the scan aborts with this error, propagated as scanErr.

Source

Thrown at pkg/meta/tkv.go:3360

		}
		return true
	})
}

func (m *kvMeta) scanPendingFiles(ctx Context, scan pendingFileScan) error {
	if scan == nil {
		return nil
	}
	// deleted files: Diiiiiiiissssssss
	klen := 1 + 8 + 8

	var scanErr error
	if err := m.client.scan(m.fmtKey("D"), func(key, val []byte) bool {
		if scanErr != nil {
			return true
		}
		if len(key) != klen {
			scanErr = fmt.Errorf("invalid key %x", key)
			return true
		}
		ino := m.decodeInode(key[1:9])
		size := binary.BigEndian.Uint64(key[9:])
		ts := m.parseInt64(val)
		_, scanErr = scan(ino, size, ts)
		return true
	}); err != nil {
		return err
	}

	return scanErr
}

func (m *kvMeta) doRepair(ctx Context, inode Ino, attr *Attr) syscall.Errno {
	prefix := m.entryKey(inode, "")
	return errno(m.txn(ctx, func(tx *kvTxn) error {
		attr.Nlink = 2

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Inspect the 'D'-prefix keys in the metadata store and remove/repair keys that are not 17 bytes long (prefix + 16 bytes payload)
2. Restore metadata from a consistent 'juicefs dump' backup
3. Ensure no other applications share the same KV namespace/prefix as the JuiceFS volume
4. Upgrade all clients to the same JuiceFS version so key encodings match

Example fix

// before (scan aborts on first bad key)
if len(key) != klen {
	scanErr = fmt.Errorf("invalid key %x", key)
	return true
}
// after (skip and continue)
if len(key) != klen {
	logger.Warnf("skip invalid key %x during scan", key)
	return false
}

// ensure metadata store namespace is dedicated and consistent
juicefs fsck <meta-url>  // run before scanning trash/gc

if err := scanTrash(); err != nil {
	var expected = "invalid key"
	if strings.Contains(err.Error(), expected) {
		// inspect D-prefix keys in the store; restore from dump backup
	}
}

When it happens

Trigger: Calling trash/deleted-size listing (e.g. juicefs info/gc or trash scan) against a TKV engine where the 'D'-prefixed key space contains a malformed or foreign key (manual writes, restored data, version mismatch).

Common situations: Restoring a TiKV/etcd namespace from a partial backup that truncated keys; another application sharing the KV namespace wrote keys under the 'D' prefix; dump/load migration artifacts.

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
• The entry of the root inode was not found
• unknown message type %d
• json: %s
• scan global user group usage: %w

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