gastownhall/beads · error

database not available: %w

Error message

database not available: %w

What it means

validateJiraConfig is the pre-flight check run by `bd jira sync/push/pull`. It first calls ensureStoreActive(); if the local bd database cannot be opened or is not initialized, the error is wrapped as 'database not available: %w'. No Jira validation happens until storage is usable.

Source

Thrown at cmd/bd/jira.go:333

	} else {
		fmt.Println("Last Sync:    Never")
	}
	fmt.Println()
	fmt.Printf("Total Issues: %d\n", len(allIssues))
	fmt.Printf("With Jira:    %d\n", withJiraRef)
	fmt.Printf("Local Only:   %d\n", pendingPush)

	if pendingPush > 0 {
		fmt.Println()
		fmt.Printf("Run 'bd jira sync --push' to push %d local issue(s) to Jira\n", pendingPush)
	}
	return nil
}

// validateJiraConfig checks that required Jira configuration is present.
func validateJiraConfig() error {
	if err := ensureStoreActive(); err != nil {
		return fmt.Errorf("database not available: %w", err)
	}

	ctx := rootCtx
	jiraURL, _ := store.GetConfig(ctx, "jira.url")

	if jiraURL == "" {
		return fmt.Errorf("jira.url not configured\nRun: bd config set jira.url \"https://company.atlassian.net\"")
	}

	// Check for project configuration (singular or plural).
	pluralProjects, _ := store.GetConfig(ctx, "jira.projects")
	singularProject, _ := store.GetConfig(ctx, "jira.project")
	projectKeys := tracker.ResolveProjectIDs(nil, pluralProjects, singularProject)
	if len(projectKeys) == 0 {
		return fmt.Errorf("no Jira project configured\nRun: bd config set jira.project \"PROJ\"\nOr:  bd config set jira.projects \"PROJ1,PROJ2\"")
	}

	apiToken, _ := store.GetConfig(ctx, "jira.api_token")

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `bd init` in the repository to create the local database
2. Verify you are in the intended repo root / workspace where .beads exists
3. Inspect the wrapped error: if Dolt connectivity is the cause, start/restart the Dolt server or fix config
4. Run `bd doctor` to diagnose the database state

Example fix

// before
$ bd jira sync
database not available: no database found
// after
$ bd init
$ bd jira sync

if _, err := os.Stat(".beads"); os.IsNotExist(err) {
    return errors.New("bd workspace missing: run `bd init` before bd jira commands")
}

if err := runJiraSync(cmd, args); err != nil {
    if strings.Contains(err.Error(), "database not available") {
        fmt.Fprintln(os.Stderr, "Run `bd init` first, then check `bd doctor`")
        os.Exit(1)
    }
    return err
}

When it happens

Trigger: Running any `bd jira` subcommand outside an initialized bd workspace, with a missing/corrupt .beads database, or when the Dolt-backed store fails to open (server down, bad config, wrong cwd).

Common situations: Running bd jira in a repo without `bd init`; deleted or corrupted .beads directory; Dolt server not reachable for synced mode; running from a subdirectory with a misconfigured database path.

Related errors

• ErrExec
• database not available: %w
• search gates: %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/9246254e82e266f7. Report an issue: GitHub.