What causes "GitHub tracker not initialized" in gastownhall/beads?

Call tracker.Init(ctx) successfully before using the tracker.

GitHub tracker not initialized

Error message

GitHub tracker not initialized

What it means

Tracker.Validate is a precondition check ensuring Init was called successfully: it only verifies that the internal HTTP client is non-nil. A nil client means the tracker struct exists but was never initialized, so no GitHub operations can proceed.

Source

Thrown at internal/github/tracker.go:86

	if repo == "" {
		return fmt.Errorf("GitHub repo not configured (set github.repo or GITHUB_REPO)")
	}

	t.client = NewClient(token, owner, repo)

	// Allow custom base URL for GitHub Enterprise
	baseURL := t.getConfig(ctx, "github.url", "GITHUB_API_URL")
	if baseURL != "" {
		t.client = t.client.WithBaseURL(baseURL)
	}

	t.config = DefaultMappingConfig()
	return nil
}

func (t *Tracker) Validate() error {
	if t.client == nil {
		return fmt.Errorf("GitHub tracker not initialized")
	}
	return nil
}

func (t *Tracker) Close() error { return nil }

func (t *Tracker) FetchIssues(ctx context.Context, opts tracker.FetchOptions) ([]tracker.TrackerIssue, error) {
	var issues []Issue
	var err error

	state := opts.State
	if state == "" {
		state = "all"
	}

	if opts.Since != nil {
		issues, err = t.client.FetchIssuesSince(ctx, state, *opts.Since)
	} else {

View on GitHub (pinned to 71377f2769)

Solutions

Call tracker.Init(ctx) successfully before using the tracker.
Check and handle the error returned by Init (see also the repo/owner configuration errors).
Ensure you are using the initialized Tracker instance, not a fresh zero-value struct.
Add a Validate() call in your own setup code to fail fast with a clear message.

Example fix

// before
t := &github.Tracker{}
t.FetchIssue(ctx, "12")
// after
t := &github.Tracker{}
if err := t.Init(ctx); err != nil { return err }
if err := t.Validate(); err != nil { return err }

Defensive patterns

Strategy: try-catch

Validate before calling

if err := t.Validate(); err != nil { return fmt.Errorf("tracker unusable: %w", err) } // call after Init, before use

Try / catch

if err := t.Init(ctx); err != nil { return err }
if err := t.Validate(); err != nil { return fmt.Errorf("init did not complete: %w", err) }

Prevention

Always construct trackers via a factory that runs Init, never as a bare struct literal.
Check Init's return error immediately; never continue on failure.
Call Validate once during application startup as a cheap invariant check.

When it happens

Trigger: Calling any operation that runs Validate on a zero-value Tracker, or on a Tracker whose Init returned early/failed, leaving t.client nil.

Common situations: Constructing github.Tracker{} directly instead of via Init, ignoring the error from Init and continuing, or reusing a Tracker across a failed configuration change.

Related errors

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