What causes "open database: %s" in juicedata/juicefs?

Verify the path portion of the fdb:// address points to an existing, readable fdb.cluster file

open database: %s

Error message

open database: %s

What it means

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.

Source

Thrown at pkg/meta/tkv_fdb.go:61

}

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{} {
	return nil
}

// simpleTxn runs f in a read-only snapshot transaction. Reads are performed
// via fdb.Snapshot, which does NOT add keys to the read conflict range, so
// the server-side resolver skips conflict tracking for these reads. This is
// safe because all callers of simpleTxn only perform point/range reads;
// attempts to write will panic on the nil `write` field of fdbTxn.

View on GitHub (pinned to c9a67b23e8)

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

Example fix

// before
juicefs mount fdb:///etc/fdb/wrong.cluster mnt
// after
juicefs mount fdb:///etc/foundationdb/fdb.cluster mnt

Defensive patterns

Strategy: validation

Validate before calling

if _, err := os.Stat(clusterFilePath); err != nil { return fmt.Errorf("fdb.cluster not found at %s", clusterFilePath) }

Prevention

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

When it happens

Trigger: 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.

Common situations: 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).

Understand the failure class

Background: "File not found" and ENOENT errors: why libraries can't find a file that should exist — this error's family across 50 libraries.

Related errors

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