juicedata/juicefs · error

check version: %s

Error message

check version: %s

What it means

baseMeta.Load checks the volume format version via format.CheckVersion() when checkVersion is true; if the on-disk format version is outside the range supported by this client, this error wraps that failure. It prevents a client from operating on a volume whose metadata layout it cannot correctly read or write.

Source

Thrown at pkg/meta/base.go:727

	}
	return fmt.Errorf("message %d is not supported", mid)
}

func (m *baseMeta) Load(checkVersion bool) (*Format, error) {
	body, err := m.en.doLoad()
	if err == nil && len(body) == 0 {
		err = fmt.Errorf("database is not formatted, please run `juicefs format ...` first")
	}
	if err != nil {
		return nil, err
	}
	var format = new(Format)
	if err = json.Unmarshal(body, format); err != nil {
		return nil, fmt.Errorf("json: %s", err)
	}
	if checkVersion {
		if err = format.CheckVersion(); err != nil {
			return nil, fmt.Errorf("check version: %s", err)
		}
	}
	if format.Tiers == nil {
		format.Tiers = object.NewTiers(format.StorageClass)
	}
	m.setFormat(format)
	return format, nil
}

func (m *baseMeta) newSessionInfo() []byte {
	host, err := os.Hostname()
	if err != nil {
		logger.Warnf("Failed to get hostname: %s", err)
	}
	ips, err := utils.FindLocalIPs(m.conf.NetworkInterfaces...)
	if err != nil {
		logger.Warnf("Failed to get local IP: %s", err)
	}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Upgrade the JuiceFS client to a version supporting the volume's format version
2. Check the volume version (in the format record / `juicefs status`) and match client versions across the cluster
3. If downgrading is required, export data and re-format with the older version — do not mount older clients directly

Example fix

// before: old client on new-format volume
./juicefs-v1.0 mount redis://meta /jfs
// after: upgrade client
./juicefs-v1.2 mount redis://meta /jfs

// before mounting, compare client support:
// juicefs status <meta-url> shows volume version; ensure client supports it

if _, err := meta.Load(true); err != nil { if strings.Contains(err.Error(), "check version") { return fmt.Errorf("upgrade client to support this volume: %w", err) } }

When it happens

Trigger: Mounting a volume created by a much newer JuiceFS with an older client (format version too high); downgrade scenarios where a newer client bumped the format version; MinClientVersion restrictions with mixed clients.

Common situations: Rolling cluster upgrades where an old client mounts after a new client bumped the version; attempts to downgrade JuiceFS; running an old binary against a recently formatted volume.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

• invalid dumped meta: missing 'Counters'
• The entry of the root inode was not found
• The entry of the root inode was not found
• failed to get startTS, which is required for TiKV to ensure
• not implemented, use kvMeta.LoadMetaV2 instead

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