gastownhall/beads · critical

database not available: %w

Error message

database not available: %w

What it means

Wraps an error from ensureStoreActive() during `bd ado sync`, meaning the local beads issue store (Dolt-backed database) could not be opened/activated. Sync needs a live local store before the ADO tracker is initialized, so this check precedes all sync work and %w preserves the driver-level cause.

Source

Thrown at cmd/bd/ado.go:517

		return err
	}

	if !adoSyncDryRun {
		CheckReadonly("ado sync")
	}

	if adoSyncPullOnly && adoSyncPushOnly {
		return fmt.Errorf("cannot use both --pull-only and --push-only")
	}

	// Validate conflict flags
	conflictStrategy, err := getADOConflictStrategy(adoPreferLocal, adoPreferADO, adoPreferNewer)
	if err != nil {
		return fmt.Errorf("%w (--prefer-local, --prefer-ado, --prefer-newer)", err)
	}

	if err := ensureStoreActive(); err != nil {
		return fmt.Errorf("database not available: %w", err)
	}

	out := cmd.OutOrStdout()
	ctx := context.Background()

	// Create and initialize the ADO tracker
	at := &ado.Tracker{}
	cliProjects, _ := cmd.Flags().GetStringSlice("project")
	if len(cliProjects) > 0 {
		at.SetProjects(tracker.DeduplicateStrings(cliProjects))
	}
	if err := at.Init(ctx, store); err != nil {
		return fmt.Errorf("initializing Azure DevOps tracker: %w", err)
	}

	// Build pull filters from CLI flags, falling back to config values.
	filters := buildADOPullFilters(ctx, cmd)
	if filters != nil {

View on GitHub (pinned to 71377f2769)

Solutions

1. Run the command from the repository root that contains .beads/.
2. Initialize if needed: `bd init`, then retry the sync.
3. If in server mode, verify the Dolt server/database is up (and credentials in metadata/config are correct).
4. Read the wrapped cause after 'database not available:' for the driver-specific problem (missing dir vs. connection refused vs. corruption).
5. Restore from git backup if the .beads store is corrupt.

Example fix

// before
$ cd ~/proj-subdir && bd ado sync
Error: database not available: no beads database found

// after
$ cd ~/proj && bd ado sync

if _, err := os.Stat(filepath.Join(cwd, ".beads")); err != nil {
	return fmt.Errorf("run from repo root with an initialized beads store: %w", err)
}
// then `bd init` if needed before `bd ado sync`

func storeReady() bool {
	_, err := os.Stat(".beads")
	return err == nil
}

if err := bd("ado", "sync"); err != nil {
	if strings.Contains(err.Error(), "database not available") {
		_ = bd("init")
		err = bd("ado", "sync")
	}
	return err
}

When it happens

Trigger: ensureStoreActive fails: no database initialized in the current directory (`bd init` never run), .beads directory missing/corrupt, Dolt server unreachable in server mode, or wrong working directory.

Common situations: Running `bd ado sync` from the wrong repo/directory; a fresh clone without `bd init` or the migrated .beads data; the embedded/local Dolt DB locked or crashed; config pointing at a backend that isn't running.

Related errors

• ErrExec
• search gates: %w
• database not available: %w
• failed to get template: %w
• db: SetLocalMetadata %s: %w

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