juicedata/juicefs · error

hex expected: %c

Error message

hex expected: %c

What it means

Returned by parseHex in pkg/meta/dump.go when a character in an %-escaped string is not a valid hex digit (0-9, A-F). unescape() decodes '%XX' sequences while parsing a metadata dump; a malformed escape produces this error.

Source

Thrown at pkg/meta/dump.go:207

			escValue = append(escValue, CHARS[c&0xF])
		} else if escValue != nil {
			n := utf8.RuneLen(r)
			escValue = append(escValue, original[i:i+n]...)
		}
	}
	if escValue == nil {
		return original
	}
	return string(escValue)
}

func parseHex(c byte) (byte, error) {
	if c >= '0' && c <= '9' {
		return c - '0', nil
	} else if c >= 'A' && c <= 'F' {
		return 10 + (c - 'A'), nil
	} else {
		return 0, fmt.Errorf("hex expected: %c", c)
	}
}

func unescape(s string) []byte {
	if !strings.ContainsRune(s, '%') {
		return []byte(s)
	}

	p := []byte(s)
	n := 0
	for i := 0; i < len(p); i++ {
		c := p[i]
		if c == '%' && i+2 < len(p) {
			h, e1 := parseHex(p[i+1])
			l, e2 := parseHex(p[i+2])
			if e1 == nil && e2 == nil {
				c = h*16 + l
				i += 2

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Fix the invalid %XX escape in the dump file (use uppercase hex digits 0-9 A-F)
2. Re-dump the metadata from the live engine with `juicefs dump` instead of repairing manually
3. Validate the file was not truncated or mangled by editors/transfer encoding

Example fix

// before (invalid escape in dump)
"name": "file%G1.txt"
// after
"name": "file%47%31.txt"

// validate percent-escapes before load
for i := 0; i+2 < len(s); i++ { if s[i]=='%' && !isHex(s[i+1])|!isHex(s[i+2]) { return fmt.Errorf("bad escape at %d", i) } }

func validHexEscapes(s string) bool { for i:=0;i+2<len(s);i++ { if s[i]=='%' { if !isHex(s[i+1]) || !isHex(s[i+2]) { return false }; i+=2 } }; return true }

if err := juicefsLoad(dumpFile); err != nil { if strings.Contains(err.Error(), "hex expected") { /* repair the dump or re-dump */ } }

When it happens

Trigger: Loading (`juicefs load`) a dumped metadata file whose names/chunks contain invalid percent-escapes such as '%G1' or a trailing '%' followed by a non-hex byte.

Common situations: Hand-edited dumps, dumps truncated/corrupted in transfer, or dumps produced by non-standard tools that percent-encode differently.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• parse name: %s
• invalid dumped meta: missing 'Counters'
• The entry of the root inode was not found
• invalid unit
• failed to parse pid: %s

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