gastownhall/beads · error

no beads configuration found in %s

Error message

no beads configuration found in %s

What it means

openDoltDB in cmd/bd/doctor/dolt.go loads the beads config file from the given beadsDir before connecting to the Dolt server. If configfile.Load succeeds but returns a nil config, it means the directory contains no beads configuration file (.beads/config.yaml), so there is nothing to drive a Dolt connection from (host/user/database). bd doctor throws this to signal the target directory is not an initialized beads workspace.

Source

Thrown at cmd/bd/doctor/dolt.go:27

	// MySQL driver for connecting to dolt sql-server
	_ "github.com/go-sql-driver/mysql"

	"github.com/steveyegge/beads/internal/configfile"
	"github.com/steveyegge/beads/internal/doltserver"

	"github.com/steveyegge/beads/internal/storage/dolt"
	"github.com/steveyegge/beads/internal/storage/doltutil"
)

// openDoltDB opens a connection to the Dolt SQL server via MySQL protocol.
func openDoltDB(beadsDir string) (*sql.DB, *configfile.Config, error) {
	cfg, err := configfile.Load(beadsDir)
	if err != nil {
		return nil, nil, fmt.Errorf("failed to load config: %w", err)
	}
	if cfg == nil {
		return nil, nil, fmt.Errorf("no beads configuration found in %s", beadsDir)
	}

	host := cfg.GetDoltServerHost()
	user := cfg.GetDoltServerUser()
	database := cfg.GetDoltDatabase()

	// Use doltserver.DefaultConfig for port resolution (env > port file > config.yaml).
	// Port 0 means no server running yet.
	dsCfg := doltserver.DefaultConfig(beadsDir)
	port := dsCfg.Port
	if port == 0 {
		return nil, nil, fmt.Errorf("no Dolt server port configured and no server running; run any bd command to auto-start")
	}

	// Resolve the password using the credentials file fallback keyed by the
	// resolved runtime port — matching the CRUD path. Env var BEADS_DOLT_PASSWORD
	// still takes precedence inside GetDoltServerPasswordForPort. Without this,
	// externally-hosted Dolt servers that keep credentials in

View on GitHub (pinned to 71377f2769)

Solutions

1. Initialize the workspace: run `bd init` (or the equivalent bd command that writes .beads/config.yaml) in the directory you are running doctor against.
2. Verify you are pointing at the correct beadsDir — check env vars like BEADS_DIR and your cwd; the config lives in the .beads directory.
3. If the config file was deleted or renamed, restore it from git history or recreate it with the dolt server host/user/database settings.

Example fix

// before
bd doctor   # run in an uninitialized directory
// after
bd init && bd doctor

if _, statErr := os.Stat(filepath.Join(beadsDir, "config.yaml")); os.IsNotExist(statErr) {
    return fmt.Errorf("not a beads workspace: %s has no config.yaml", beadsDir)
}

cfg, err := configfile.Load(beadsDir)
if err != nil {
    return err
}
if cfg == nil {
    return fmt.Errorf("no beads configuration in %s; run bd init", beadsDir)
}

When it happens

Trigger: Calling openDoltDB (via openDoltConn or querySQLRemotes during `bd doctor` dolt checks) with a beadsDir where configfile.Load returns (nil, nil) — i.e., no .beads/config.yaml (or equivalent config file) exists in that directory.

Common situations: Running `bd doctor` in a directory that was never `bd init`ed; pointing BEADS_DIR or cwd at the wrong path (repo root instead of the .beads dir or vice versa); a deleted or renamed config.yaml; running doctor before first sync/setup in a fresh clone.

Related errors

• multiple .doltcfg directories detected
• dolt directory is required
• ErrFSCKTimeout
• database %q not found on Dolt server at %s:%d
• not using Dolt backend (configured backend %q)

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/f179b6996b2261fc. Report an issue: GitHub.