What causes "database not available: %w" in gastownhall/beads?

Run `bd init` in the repository (or cd into the bd-initialized repo) before running linear commands

database not available: %w

Error message

database not available: %w

What it means

validateLinearConfig begins by calling ensureStoreActive(); every Linear sync/push/pull command requires an active bd database (Dolt-backed store). If no database is available or active, the underlying error is wrapped as 'database not available'.

Source

Thrown at cmd/bd/linear.go:1004

	}
	if dbPath != "" {
		return resolveCommandBeadsDir(dbPath)
	}
	return ""
}

// uuidRegex matches valid UUID format (with or without hyphens).
var uuidRegex = regexp.MustCompile(`^[0-9a-fA-F]{8}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{4}-?[0-9a-fA-F]{12}$`)

func isValidUUID(s string) bool {
	return uuidRegex.MatchString(s)
}

// validateLinearConfig checks that required Linear configuration is present.
// cliTeams is the list of team IDs from the --team flag (may be nil).
func validateLinearConfig(cliTeams []string) error {
	if err := ensureStoreActive(); err != nil {
		return fmt.Errorf("database not available: %w", err)
	}

	ctx := rootCtx

	// Accept either OAuth credentials or API key.
	oauthClientID, _ := getLinearConfig(ctx, "linear.oauth_client_id")
	oauthClientSecret, _ := getLinearConfig(ctx, "linear.oauth_client_secret")
	hasOAuth := oauthClientID != "" && oauthClientSecret != ""

	if !hasOAuth {
		apiKey, _ := getLinearConfig(ctx, "linear.api_key")
		if apiKey == "" {
			return fmt.Errorf("Linear authentication not configured\n" +
				"Options:\n" +
				"  OAuth (for CI):  export LINEAR_OAUTH_CLIENT_ID=... LINEAR_OAUTH_CLIENT_SECRET=...\n" +
				"  API key (devs):  export LINEAR_API_KEY=... or bd config set linear.api_key \"YOUR_API_KEY\"")
		}
	}

View on GitHub (pinned to 71377f2769)

Solutions

Run `bd init` in the repository (or cd into the bd-initialized repo) before running linear commands
Check/start the bd daemon (`bd doctor`, restart `bd daemon`)
Verify the .beads/Dolt database files exist and are not corrupted; restore from backup if needed

Example fix

// before
$ cd ~/somewhere && bd linear pull
Error: database not available: ...
// after
$ cd ~/myproject && bd init && bd linear pull

Defensive patterns

Strategy: validation

Validate before calling

if _, err := os.Stat(".beads"); err != nil {
	return fmt.Errorf("run 'bd init' first: %w", err)
}
if err := exec.Command("bd", "doctor").Run(); err != nil {
	return fmt.Errorf("bd store unhealthy")
}

Try / catch

err := validateLinearConfig(cliTeams)
if err != nil && strings.Contains(err.Error(), "database not available") {
	// prompt/run: bd init, restart daemon, then retry
}

Prevention

Always run bd commands inside a bd-initialized repository
Keep the bd daemon healthy and monitored in CI
Back up the Dolt database and verify with bd doctor

When it happens

Trigger: Running bd linear sync/push/pull outside a bd-initialized directory, with BD_DAEMON/daemon store not connected, or when the embedded/Dolt store failed to open.

Common situations: Running the command in a repo without `bd init`; the bd daemon is not running or crashed; the Dolt database directory is missing or corrupted; wrong working directory.

Related errors

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