{"record":{"id":"88fbac9796f176f7","repo":"juicedata/juicefs","slug":"set-api-version-s","errorCode":null,"errorMessage":"set API version: %s","messagePattern":"set API version: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/tkv_fdb.go","lineNumber":53,"sourceCode":"\tRegister(\"fdb\", newKVMeta)\n\tdrivers[\"fdb\"] = newFdbClient\n}\n\ntype fdbTxn struct {\n\tfdb.ReadTransaction\n\twrite fdb.Transaction\n\tc     *fdbClient\n}\n\ntype fdbClient struct {\n\tclient fdb.Database\n\tnextid uint64\n}\n\nfunc newFdbClient(addr string) (tkvClient, error) {\n\terr := fdb.APIVersion(630)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"set API version: %s\", err)\n\t}\n\tu, err := url.Parse(\"fdb://\" + addr)\n\tif err != nil {\n\t\treturn nil, err\n\t}\n\tdb, err := fdb.OpenDatabase(u.Path)\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"open database: %s\", err)\n\t}\n\t// TODO: database options\n\treturn withPrefix(&fdbClient{db, rand.Uint64()}, append([]byte(u.Query().Get(\"prefix\")), 0xFD)), nil\n}\n\nfunc (c *fdbClient) name() string {\n\treturn \"fdb\"\n}\n\nfunc (c *fdbClient) config(key string) interface{} {","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/tkv_fdb.go#L35-L71","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Upgrade the FoundationDB client package (libfdb_c) to >= 6.3.x so API version 630 is supported","Check the installed client version with `fdbcli --version` and align it with the version the juicefs fdb bindings expect","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","Rebuild juicefs after updating github.com/apple/foundationdb/bindings/go so bindings and client library match"],"exampleFix":"// before (client lib supports only 620)\nerr := fdb.APIVersion(630)\n// after: upgrade libfdb_c to >=6.3, or lower to a supported version\nerr := fdb.APIVersion(620)","handlingStrategy":"validation","validationCode":"out, err := exec.Command(\"fdbcli\", \"--version\").Output()\nif err != nil || !strings.Contains(string(out), \"6.\") { /* client lib missing/too old for API 630 */ }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Pin the FoundationDB client package version to >= 6.3 in deployment images","Verify `fdbcli --version` during environment setup before mounting with the fdb engine","Keep fdb go bindings and libfdb_c upgraded together"],"tags":["foundationdb","version-mismatch","metadata"],"backgroundTag":"fdb-api-version-mismatch","analyzedSha":"c9a67b23e8e08ec23ec331aa6f1675e2319e921c","analyzedAt":"2026-09-06T17:55:48.476Z","contentChangedAt":"2026-09-06T17:55:48.476Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}