juicedata/juicefs · error

update format

Error message

update format

What it means

At the end of doInit for SQL metadata, `format.update(&old, force)` validates the new format against the stored one (e.g. name/UUID changes, secret key mismatch, incompatible settings). If validation fails, the error is wrapped as "update format" and `juicefs format` aborts without changing the volume.

Source

Thrown at pkg/meta/sql.go:664

				return errors.Wrap(err, "drop table dirStats")
			}
		}
		if !old.UserGroupQuota && format.UserGroupQuota {
			// remove user group quota as they are outdated
			err = m.txn(func(s *xorm.Session) error {
				_, err := s.Where("TRUE").Delete(new(userGroupQuota))
				if err != nil {
					return err
				}
				m.genLog(Background(), s, time.Now().UnixNano(), "INIT_ENABLE_USERGROUPQUOTA()")
				return nil
			})
			if err != nil {
				return errors.Wrap(err, "drop table userGroupQuota")
			}
		}
		if err = format.update(&old, force); err != nil {
			return errors.Wrap(err, "update format")
		}
	}

	data, err := json.MarshalIndent(format, "", "")
	if err != nil {
		return fmt.Errorf("json: %s", err)
	}

	m.setFormat(format)
	n := &node{
		Type:   TypeDirectory,
		Nlink:  2,
		Length: 4 << 10,
		Parent: RootInode,
	}
	now := time.Now().UnixNano()
	n.setAtime(now)
	n.setMtime(now)

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Read the wrapped cause: if it is a secret key mismatch, provide the original secret key
2. Use `juicefs config <meta-url> --secret-key ...` or `--force` intentionally to change settings instead of re-formatting
3. Do not change the volume name on an existing metadata URL
4. If the volume is new/unwanted, drop the metadata tables or use a fresh metadata URL

Example fix

// before
juicefs format sqlite3://test.db myjfs2   # name mismatch
// after
juicefs format sqlite3://test.db myjfs    # keep the original volume name

// compare intended format against stored one first
stored, _ := juicefsStatus(metaURL)
if stored.Name != newName || stored.SecretKey != newSecret { /* fix before formatting */ }

if err != nil && strings.Contains(err.Error(), "update format") {
    // use the wrapped cause: name/secret mismatch => supply original values or use `juicefs config`
}

When it happens

Trigger: Running `juicefs format` against an existing volume with a changed name, mismatched secret key (without --force), or format fields that cannot be updated; also reached after the dirStats/userGroupQuota cleanup steps above.

Common situations: Typo in volume name or secret key when reformatting; trying to change immutable fields; using `juicefs format` where `juicefs config` should be used; scripting a format step against an already-initialized volume.

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 dumped meta: missing 'Counters'
• invalid magic number %d, expect %d
• load meta format
• drop table dirStats
• update format

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