gastownhall/beads · warning

no database configuration found

Error message

no database configuration found

What it means

openDoltDB is the shared connection helper for doctor fix routines. It first loads the database config via configfile.Load(beadsDir); if loading errors or returns nil (no config file present), it returns the sentinel error "no database configuration found". This is not a connection failure — beads cannot even determine which Dolt server/database to dial.

Source

Thrown at cmd/bd/doctor/fix/validation.go:327

	}
	defer db.Close()

	var count int
	if err := db.QueryRow(`SELECT COUNT(*) FROM issues WHERE id IN (SELECT id FROM wisps)`).Scan(&count); err != nil {
		return 0, fmt.Errorf("query cross-table duplicates: %w", err)
	}
	return count, nil
}

// openDoltDB opens a Dolt database connection via MySQL protocol.
// Delegates to openFixDB for DSN construction (timeout + password support).
// Also returns the loaded config so callers that need it afterward (e.g. to
// verify the connection's target identity) don't have to load it a second
// time and risk it disagreeing with what was actually dialed.
func openDoltDB(beadsDir string) (*sql.DB, *configfile.Config, error) {
	cfg, err := configfile.Load(beadsDir)
	if err != nil || cfg == nil {
		return nil, nil, fmt.Errorf("no database configuration found")
	}

	db, err := openFixDB(beadsDir, cfg)
	if err != nil {
		return nil, nil, fmt.Errorf("dolt server connection failed: %w", err)
	}

	// Verify the connection actually works
	if err := db.Ping(); err != nil {
		_ = db.Close() // Best effort cleanup
		return nil, nil, fmt.Errorf("dolt server not reachable: %w", err)
	}

	return db, cfg, nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Initialize the workspace: run `bd init` (or `bd doctor`) so .beads/config.json is created
2. Point the command at the correct repo/beads directory (check the path argument)
3. Inspect .beads/config.json for corruption or bad JSON and repair or regenerate it
4. Check file permissions on .beads/ so the process can read the config

Example fix

// before: running fix in a directory with no beads config
$ cd /tmp && bd doctor --fix
  Orphaned dependencies fix skipped (no database configuration found)
// after: run from the repo root with an initialized .beads
$ cd ~/my-repo && bd init && bd doctor --fix

// Check config presence before calling fix routines that open the DB
beadsDir := filepath.Join(repoRoot, ".beads")
if _, err := os.Stat(filepath.Join(beadsDir, "config.json")); err != nil {
    return fmt.Errorf("not a beads workspace: run 'bd init' in %s", repoRoot)
}

db, cfg, err := openDoltDB(beadsDir)
if err != nil {
    if strings.Contains(err.Error(), "no database configuration found") {
        // not an initialized workspace: skip fix, don't crash
        fmt.Println("fix skipped: run 'bd init' first")
        return nil
    }
    return err
}

When it happens

Trigger: configfile.Load(beadsDir) returns an error (malformed/unreadable config JSON) or nil config (.beads/config.json absent) while any fix routine (OrphanedDependencies, RecomputeBlocked, DependencyKeys, etc.) tries to open the DB.

Common situations: Running `bd doctor --fix` outside an initialized beads workspace (no .beads directory); config.json deleted or corrupted; wrong --path/beadsDir pointing at a directory that isn't a beads root; permissions blocking the config read.

Related errors

• no database connection
• failed to load config: %w
• no .beads/ directory found at %s; run 'bd init' to initializ
• loading status configuration: %w
• no database — run 'bd init' or 'bd bootstrap' first

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