juicedata/juicefs · error

version is nil

Error message

version is nil

What it means

CheckCliVersion rejects a nil client version pointer. It compares the running client's semver against the volume format's MinClientVersion; if the passed version is nil there is nothing to compare, so it returns this error.

Source

Thrown at pkg/meta/config.go:181

func (f *Format) String() string {
	t := *f
	t.RemoveSecret()
	s, _ := json.MarshalIndent(t, "", "  ")
	return string(s)
}

func (f *Format) CheckVersion() error {
	if f.MetaVersion > MaxVersion {
		return fmt.Errorf("incompatible metadata version: %d; please upgrade the client", f.MetaVersion)
	}

	ver := version.GetVersion()
	return f.CheckCliVersion(&ver)
}

func (f *Format) CheckCliVersion(ver *version.Semver) error {
	if ver == nil {
		return errors.New("version is nil")
	}

	if f.MinClientVersion != "" {
		minClientVer := version.Parse(f.MinClientVersion)
		r, err := version.CompareVersions(ver, minClientVer)
		if err == nil && r < 0 {
			err = fmt.Errorf("allowed minimum version: %s; please upgrade the client", f.MinClientVersion)
		}
		if err != nil {
			return err
		}
	}
	if f.MaxClientVersion != "" {
		maxClientVer := version.Parse(f.MaxClientVersion)
		r, err := version.CompareVersions(ver, maxClientVer)
		if err == nil && r > 0 {
			err = fmt.Errorf("allowed maximum version: %s; please use an older client", f.MaxClientVersion)
		}

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Initialize the version properly: pass &version.Semver from version.GetVersion() and ensure build-time version variables are set.
2. Guard callers so they never call CheckCliVersion with a nil pointer.
3. If embedding, hard-code a valid Semver matching the client build.

Example fix

// before
var ver *version.Semver
err := format.CheckCliVersion(ver)
// after
v := version.GetVersion()
err := format.CheckCliVersion(&v)

func safeCheckVersion(f *meta.Format) error {
	v := version.GetVersion()
	if v == nil { return errors.New("client version unavailable") }
	return f.CheckCliVersion(&v)
}

When it happens

Trigger: Calling Format.CheckCliVersion(nil), or indirectly CheckVersion when version.GetVersion() yields a nil pointer (abnormal/uninitialized version info).

Common situations: Embedding juicefs as a library and passing an uninitialized *version.Semver; builds with stripped version metadata producing an unset version.

Related errors

• Invalid version string: %s
• allowed minimum version: %s; please upgrade the client
• allowed maximum version: %s; please use an older client
• illegal value for parameter 'ranger-service': " + serviceNam
• No sources given

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