What causes "invalid key %s, fail to parse id" in juicedata/juicefs?

Inspect the offending key with redis-cli (the key name is in the message) and delete it if it is not a valid pending slice.

juicedata/juicefs · warning

invalid key %s, fail to parse id

Error message

invalid key %s, fail to parse id

What it means

Raised while scanning pending (uncommitted) slices stored as Redis keys of the form "<id>_<size>" during GC. The key's id portion could not be parsed with strconv.ParseUint, meaning the metadata engine found a pending-slice key that does not follow the expected "<inode/slice-id>_<size>" layout — indicating key corruption or unexpected data in the pending-slices keyspace.

Source

Thrown at pkg/meta/redis.go:4194

					return nil
				}
				if refs < 0 {
					pendingKeys <- keys[i]
				}
			}
			return nil
		})
		close(pendingKeys)
	}()

	for key := range pendingKeys {
		ps := strings.Split(key[1:], "_")
		if len(ps) != 2 {
			return fmt.Errorf("invalid key %s", key)
		}
		id, err := strconv.ParseUint(ps[0], 10, 64)
		if err != nil {
			return errors.Wrapf(err, "invalid key %s, fail to parse id", key)
		}
		size, err := strconv.ParseUint(ps[1], 10, 64)
		if err != nil {
			return errors.Wrapf(err, "invalid key %s, fail to parse size", key)
		}
		clean, err := scan(id, uint32(size))
		if err != nil {
			return errors.Wrap(err, "scan pending slices")
		}
		if clean {
			// TODO: m.deleteSlice(id, uint32(size))
			// avoid lint warning
			_ = clean
		}
	}
	return nil
}

View on GitHub (pinned to c9a67b23e8)

Solutions

Inspect the offending key with redis-cli (the key name is in the message) and delete it if it is not a valid pending slice.
Confirm the Redis DB is exclusively used by JuiceFS (shared databases often accumulate foreign keys).
Check whether the keys were produced by an incompatible JuiceFS version and upgrade/downgrade accordingly.
Re-run `juicefs gc` after cleanup; GC is resumable and idempotent per key.

Defensive patterns

Strategy: validation

Validate before calling

// Validate pending-slice key format before processing:
parts := strings.Split(key, "_")
if len(parts) != 2 { /* skip/report foreign key */ }
if _, err := strconv.ParseUint(parts[0], 10, 64); err != nil { /* corrupt key */ }

Type guard

func validPendingSliceKey(key string) bool {
    ps := strings.Split(strings.TrimPrefix(key, setting.Name+"\x00"), "_")
    if len(ps) != 2 { return false }
    _, e1 := strconv.ParseUint(ps[0], 10, 64)
    _, e2 := strconv.ParseUint(ps[1], 10, 64)
    return e1 == nil && e2 == nil
}

Try / catch

if err := gc(); err != nil {
    var ke *ParseKeyError
    if stderrors.As(err, &ke) { logger.Warnf("skip corrupt key %s", ke.Key); return nil }
    return err
}

Prevention

Dedicate the Redis DB to JuiceFS; never share keyspaces with other apps.
Do not manually insert or edit keys in the metadata engine.
Keep all clients on the same JuiceFS major version.
Periodically audit the pending-slices keyspace for foreign keys.

When it happens

Trigger: Running `juicefs gc` (scanPendingSlices) when a key in the pending-slices keyspace parses into the wrong number of parts (already reported as "invalid key") or its id segment is not a valid base-10 uint64.

Common situations: Manually written/corrupted keys in Redis; keys left by a different or much older JuiceFS version with a different key format; accidental writes into the JuiceFS keyspace by other tools.

Understand the failure class

Background: "invalid id" errors: invalid identifier format — why libraries reject IDs before lookup, and how to fix them — this error's family across 37 libraries.

Related errors

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