juicedata/juicefs · error

set API version: %s

Error message

set API version: %s

What it means

newFdbClient in pkg/meta/tkv_fdb.go calls fdb.APIVersion(630) to pin the FoundationDB client API version before opening the database. The error is wrapped when the installed FoundationDB client library refuses or cannot support API version 630. It means the Go binding could not negotiate the requested API version, so no FDB metadata engine can be created.

Source

Thrown at pkg/meta/tkv_fdb.go:53

	Register("fdb", newKVMeta)
	drivers["fdb"] = newFdbClient
}

type fdbTxn struct {
	fdb.ReadTransaction
	write fdb.Transaction
	c     *fdbClient
}

type fdbClient struct {
	client fdb.Database
	nextid uint64
}

func newFdbClient(addr string) (tkvClient, error) {
	err := fdb.APIVersion(630)
	if err != nil {
		return nil, fmt.Errorf("set API version: %s", err)
	}
	u, err := url.Parse("fdb://" + addr)
	if err != nil {
		return nil, err
	}
	db, err := fdb.OpenDatabase(u.Path)
	if err != nil {
		return nil, fmt.Errorf("open database: %s", err)
	}
	// TODO: database options
	return withPrefix(&fdbClient{db, rand.Uint64()}, append([]byte(u.Query().Get("prefix")), 0xFD)), nil
}

func (c *fdbClient) name() string {
	return "fdb"
}

func (c *fdbClient) config(key string) interface{} {

View on GitHub (pinned to c9a67b23e8)

Solutions

1. Upgrade the FoundationDB client package (libfdb_c) to >= 6.3.x so API version 630 is supported
2. Check the installed client version with `fdbcli --version` and align it with the version the juicefs fdb bindings expect
3. If the cluster must stay on an older FDB release, downgrade/change the requested API version in tkv_fdb.go to one the client supports
4. Rebuild juicefs after updating github.com/apple/foundationdb/bindings/go so bindings and client library match

Example fix

// before (client lib supports only 620)
err := fdb.APIVersion(630)
// after: upgrade libfdb_c to >=6.3, or lower to a supported version
err := fdb.APIVersion(620)

out, err := exec.Command("fdbcli", "--version").Output()
if err != nil || !strings.Contains(string(out), "6.") { /* client lib missing/too old for API 630 */ }

When it happens

Trigger: Calling newFdbClient (via TestFdb or a `--engine fdb` mount) when the installed libfdb_c version is older than 6.3.0, when the FoundationDB bindings were built against a different API version, or when no client library is available at all.

Common situations: Deploying JuiceFS on a host whose FoundationDB client is older than the server/cluster; upgrading the FDB cluster without upgrading client libraries; building with a stale fdb go bindings version; running in a container without libfdb_c installed.

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/88fbac9796f176f7. Report an issue: GitHub.