{"record":{"id":"302db2bd2e705099","repo":"juicedata/juicefs","slug":"open-database-s","errorCode":null,"errorMessage":"open database: %s","messagePattern":"open database: (.+?)","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"pkg/meta/tkv_fdb.go","lineNumber":61,"sourceCode":"}\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{} {\n\treturn nil\n}\n\n// simpleTxn runs f in a read-only snapshot transaction. Reads are performed\n// via fdb.Snapshot, which does NOT add keys to the read conflict range, so\n// the server-side resolver skips conflict tracking for these reads. This is\n// safe because all callers of simpleTxn only perform point/range reads;\n// attempts to write will panic on the nil `write` field of fdbTxn.","sourceCodeStart":43,"sourceCodeEnd":79,"githubUrl":"https://github.com/juicedata/juicefs/blob/c9a67b23e8e08ec23ec331aa6f1675e2319e921c/pkg/meta/tkv_fdb.go#L43-L79","documentation":"After parsing the fdb:// address, newFdbClient calls fdb.OpenDatabase(u.Path) to connect to the FoundationDB cluster described by the fdb.cluster file found via the path or FDB_CLUSTER_FILE. The error is wrapped when the client cannot open the database: missing cluster file, wrong path, or unreachable cluster. The metadata engine cannot start as a result.","triggerScenarios":"Passing an addr whose path does not point to a valid fdb.cluster file; FDB_CLUSTER_FILE pointing at a nonexistent or unreadable file; FoundationDB server down or unreachable from the client host.","commonSituations":"Mounting with `--engine fdb:///wrong/path/fdb.cluster`; running juicefs outside the FDB container/host where fdb.cluster lives; forgetting to copy fdb.cluster to the client; FDB cluster process not running (connection refused).","solutions":["Verify the path portion of the fdb:// address points to an existing, readable fdb.cluster file","Set FDB_CLUSTER_FILE to the correct fdb.cluster location, or copy fdb.cluster from a cluster node","Confirm the FoundationDB cluster is up with `fdbcli -C <clusterfile> status`","Check network/firewall reachability of the cluster's coordinators from the client host"],"exampleFix":"// before\njuicefs mount fdb:///etc/fdb/wrong.cluster mnt\n// after\njuicefs mount fdb:///etc/foundationdb/fdb.cluster mnt","handlingStrategy":"validation","validationCode":"if _, err := os.Stat(clusterFilePath); err != nil { return fmt.Errorf(\"fdb.cluster not found at %s\", clusterFilePath) }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always pass the full path to fdb.cluster in the fdb:// address","Copy fdb.cluster onto every client host or set FDB_CLUSTER_FILE consistently","Confirm cluster health with fdbcli before starting JuiceFS"],"tags":["foundationdb","connection","cluster-file"],"backgroundTag":"file-not-found","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"}