gastownhall/beads · error

initializing Azure DevOps tracker: %w

Error message

initializing Azure DevOps tracker: %w

What it means

Wraps a failure from at.Init(ctx, store) when `bd ado sync` constructs and initializes the Azure DevOps tracker (ado.Tracker). Init validates ADO credentials/organization, resolves the project list (CLI --project flags take precedence, deduplicated), and prepares sync metadata against the local store; any failure here is reported with this message and the %w cause.

Source

Thrown at cmd/bd/ado.go:530

	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 {
		if err := filters.Validate(); err != nil {
			return fmt.Errorf("invalid pull filter: %w", err)
		}
		at.SetFilters(filters)
	}

	// Create the sync engine
	engine := tracker.NewEngine(at, store, actor)
	var warnings []string
	if !jsonOutput {
		engine.OnMessage = func(msg string) { _, _ = fmt.Fprintln(out, "  "+msg) }
	}
	engine.OnWarning = func(msg string) {

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped cause after 'initializing Azure DevOps tracker:' — it identifies which Init step failed.
2. Validate project names: `bd ado projects` and only pass names from that list to --project.
3. Re-check ado.pat/ado.org (or AZURE_DEVOPS_PAT/AZURE_DEVOPS_ORG) values and PAT scope.
4. If local tracker state is suspect, run `bd doctor` or re-init per the docs before re-syncing.
5. Retry `bd ado sync` after correcting the config.

Example fix

// before
bd ado sync --project "My Proj "   # trailing space, unknown project

// after
bd ado projects           # confirm exact names
bd ado sync --project "My Project"

names, err := runADOProjects(cmd, nil) // discover valid projects first
if err != nil { return err }
for _, p := range cliProjects {
	if !slices.Contains(names, p) {
		return fmt.Errorf("unknown project %q", p)
	}
}

func isTrackerInitError(err error) bool {
	return err != nil && strings.Contains(err.Error(), "initializing Azure DevOps tracker")
}

if err := bd("ado", "sync", args...); err != nil {
	if isTrackerInitError(err) {
		log.Printf("tracker init failed: %v — check ado.pat/ado.org and --project names", err)
	}
	return err
}

When it happens

Trigger: at.Init returning an error: missing/invalid ADO config at tracker level, unknown --project names not found in the org, store queries failing while loading tracker state, or auth handshake with Azure DevOps failing.

Common situations: Misspelled project passed via --project; PAT valid but lacking access to a specific project; tracker metadata in the local store out of sync after a manual .beads edit; org value pointing at an org the PAT cannot read.

Related errors

• invalid pull filter: %w
• Failed to fetch ADO #%d for link sync: %v
• Link sync ADO #%d: %v
• cannot use multiple conflict resolution flags
• ado.pat not configured: set via 'bd config set ado.pat <toke

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