What causes "decode %v: %s" in juicedata/juicefs?

Inspect the named field around the reported position in the dump file and fix or remove the malformed value.

decode %v: %s

Error message

decode %v: %s

What it means

While loading a dumped metadata entry, decoding of one of the entry's fields (attributes, symlink target, xattr, or a POSIX ACL) failed. The error wraps the failing field name and the underlying decoder error. It indicates the dump entry contains a value that cannot be decoded into the expected Go type.

Source

Thrown at pkg/meta/dump.go:634

					var t json.Token
					t, err = dec.Token()
					if err == nil && t != json.Delim('}') {
						err = fmt.Errorf("unexpected %v", t)
					}
				}
			}
		case "symlink":
			err = dec.Decode(&e.Symlink)
		case "xattrs":
			err = dec.Decode(&e.Xattrs)
		case "posix_acl_access":
			err = dec.Decode(&e.AccessACL)
		case "posix_acl_default":
			err = dec.Decode(&e.DefaultACL)
		}
		if err != nil {
			return nil, fmt.Errorf("decode %v: %s", name, err)
		}
	}
	if len(e.Parents) == 1 {
		load(&e)
		bar.Increment()
	}
	if _, err := dec.Token(); err != nil {
		return nil, err
	}
	return &e, nil
}

func dumpACL(rule *aclAPI.Rule) *DumpedACL {
	if rule == nil {
		return nil
	}
	return &DumpedACL{
		Owner:  rule.Owner,

View on GitHub (pinned to c9a67b23e8)

Solutions

Inspect the named field around the reported position in the dump file and fix or remove the malformed value.
Upgrade the juicefs binary doing the load to a version at least as new as the one that produced the dump.
Re-dump from the source metadata engine and retry.
Verify the dump wasn't corrupted in transfer (checksum comparison).

Example fix

// before: old binary loading dump with new ACL fields
$ juicefs-v1.0 load sqlite3://meta.db dump-with-acls
// after
$ juicefs-v1.2 load sqlite3://meta.db dump-with-acls

Defensive patterns

Strategy: try-catch

Try / catch

if err := loadDump(...); err != nil {
    var de *DecodeError // or inspect the wrapped error
    if strings.HasPrefix(err.Error(), "decode ") { /* field-level decode failure: check dump version/fields */ }
}

Prevention

Keep the loading binary version >= the dumping binary version.
Validate dumps against a JSON schema before load.
Test load/restore round-trips in staging before production restores.

When it happens

Trigger: The decoder hits a field (e.g. `posix_acl_access`, `posix_acl_default`, `xattrs`, `symlink`) whose JSON value does not match the target struct, or the underlying stream has an IO/JSON error mid-entry; loadFiles returns `decode <name>: <err>`.

Common situations: Loading a dump produced by a newer JuiceFS version with fields an older binary can't decode; corrupted dump content for an ACL or xattr; ACL feature data present but the target entry struct type mismatched.

Understand the failure class

Background: "failed to unmarshal" / json.Unmarshal errors: why parsing a response into a Go struct fails and how to fix it — this error's family across 23 libraries.

Related errors

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