gastownhall/beads · error

failed to load config: %w

Error message

failed to load config: %w

What it means

openDoltDB loads the beads configuration file from the .beads directory before connecting to the Dolt SQL server. If configfile.Load fails (unreadable or malformed config), the error is wrapped here and propagates to openDoltConn/querySQLRemotes used by doctor's Dolt checks.

Source

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

	"fmt"
	"strings"
	"time"

	// 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

View on GitHub (pinned to 71377f2769)

Solutions

1. Run bd from (or point it at) a directory initialized with `bd init` so .beads/config.json exists
2. Check ~/.beads or project .beads/config.json: verify it's readable and valid JSON (jq . config.json)
3. Fix permissions: chown/chmod .beads/config.json to your user
4. Restore a corrupt config (git checkout .beads/config.json or re-run bd init) and re-run bd doctor

Example fix

# before
$ ls .beads/        # empty or missing config.json
# after
$ bd init
$ ls .beads/config.json && jq . .beads/config.json

import "os", "encoding/json"
func beadsConfigExists(beadsDir string) error {
	p := filepath.Join(beadsDir, "config.json")
	data, err := os.ReadFile(p)
	if err != nil { return fmt.Errorf("%s: %w", p, err) }
	var v map[string]any
	if err := json.Unmarshal(data, &v); err != nil {
		return fmt.Errorf("%s invalid JSON: %w", p, err)
	}
	return nil
}

db, cfg, err := openDoltDB(beadsDir)
if err != nil {
	if strings.Contains(err.Error(), "failed to load config") {
		log.Printf("run `bd init` in this directory or fix .beads/config.json: %v", err)
		return errSkipDoltChecks
	}
	return err
}

When it happens

Trigger: openDoltDB (via openDoltConn/querySQLRemotes in `bd doctor` Dolt diagnostics) when configfile.Load(beadsDir) returns an error — missing/unreadable config.json in .beads, or JSON parse failure — at cmd/bd/doctor/dolt.go:24.

Common situations: Running bd doctor outside a beads-initialized directory or in the wrong one; .beads/config.json corrupted by a partial write or hand edit; restrictive file permissions; running as a different user than the one who initialized beads.

Related errors

• failed to commit is_blocked repairs to Dolt: %w
• failed to scan dependency keys: %w
• failed to begin transaction: %w
• failed to commit dependency key repairs: %w
• failed to query orphaned dependencies: %w

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