Jira API token not configured Run: bd config set jira.api_to

Error message

Jira API token not configured
Run: bd config set jira.api_token "YOUR_TOKEN"
Or: export JIRA_API_TOKEN=YOUR_TOKEN

What it means

The final check in validateJiraConfig requires an API token: either the 'jira.api_token' config key or the JIRA_API_TOKEN environment variable must be non-empty. Without credentials, Jira API calls would fail authentication, so bd refuses up front with this fixed remediation message.

Source

Thrown at cmd/bd/jira.go:353

	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")
	if apiToken == "" && os.Getenv("JIRA_API_TOKEN") == "" {
		return fmt.Errorf("Jira API token not configured\nRun: bd config set jira.api_token \"YOUR_TOKEN\"\nOr: export JIRA_API_TOKEN=YOUR_TOKEN")
	}

	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

Export the token: export JIRA_API_TOKEN=YOUR_TOKEN
Or persist it: bd config set jira.api_token "YOUR_TOKEN"
Verify with bd config get jira.api_token (or echo $JIRA_API_TOKEN), then re-run; prefer the env var in CI to avoid storing secrets

Example fix

// before
$ bd jira sync
Jira API token not configured
// after (CI-safe)
$ export JIRA_API_TOKEN=$ATLASSIAN_TOKEN
$ bd jira sync

Defensive patterns

Strategy: validation

Validate before calling

tok, _ := store.GetConfig(ctx, "jira.api_token")
if strings.TrimSpace(tok) == "" && os.Getenv("JIRA_API_TOKEN") == "" {
    return errors.New("Jira API token missing: export JIRA_API_TOKEN or run bd config set jira.api_token")
}

Try / catch

if err := runJiraPull(cmd, args); err != nil {
    if strings.Contains(err.Error(), "Jira API token not configured") {
        fmt.Fprintln(os.Stderr, "Export JIRA_API_TOKEN or set jira.api_token")
        os.Exit(1)
    }
    return err
}

Prevention

Export JIRA_API_TOKEN in CI job environment rather than storing in config
Source your secrets profile before running bd jira commands
Re-set the token after rotating Jira credentials
Prefer the env var in shared environments so secrets never enter the database

When it happens

Trigger: Running `bd jira sync|push|pull` when both store config 'jira.api_token' is empty and env var JIRA_API_TOKEN is unset or empty.

Common situations: Token set in shell profile but not exported in the current shell/CI job; token stored on a teammate's machine only; expired/rotated token removed from config; secrets excluded from synced config for security.

Related errors

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