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

Call Init (or the constructor) and check its error before calling Validate

Jira tracker not initialized

Error message

Jira tracker not initialized

What it means

Tracker.Validate is a pre-flight sanity check that the Jira tracker has a usable HTTP client. The client is only set up during Init; if Validate is called on a Tracker constructed without Init (or whose construction failed), the nil client check fails and this error is returned so callers don't hit a nil-pointer panic later.

Source

Thrown at internal/jira/tracker.go:175

				typeCustomFields[parts[0]][parts[1]] = parsed
				continue
			}
			customFields[suffix] = parsed
		}
		if len(customFields) > 0 {
			t.customFields = customFields
		}
		if len(typeCustomFields) > 0 {
			t.typeCustomFields = typeCustomFields
		}
	}

	return nil
}

func (t *Tracker) Validate() error {
	if t.client == nil {
		return fmt.Errorf("Jira 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) {
	// Build JQL query — use IN clause for multi-project.
	var jql string
	if len(t.projectKeys) == 1 {
		jql = fmt.Sprintf("project = %q", t.projectKeys[0])
	} else {
		quoted := make([]string, len(t.projectKeys))
		for i, k := range t.projectKeys {
			quoted[i] = fmt.Sprintf("%q", k)
		}
		jql = fmt.Sprintf("project IN (%s)", strings.Join(quoted, ", "))
	}

View on GitHub (pinned to 71377f2769)

Solutions

Call Init (or the constructor) and check its error before calling Validate
Ensure initialization ordering so Validate always runs after successful Init
If Init failed, fix the underlying config/credentials error instead of proceeding to Validate
In tests, use the real constructor rather than a zero-value Tracker literal

Example fix

// before
t := &jira.Tracker{}
if err := t.Validate(); err != nil { ... }
// after
t, err := jira.NewTracker(cfg) // or t.Init(ctx, cfg)
if err != nil { return err }
if err := t.Validate(); err != nil { return err }

Defensive patterns

Strategy: validation

Validate before calling

if tracker == nil || tracker.Validate() != nil {
	return fmt.Errorf("tracker not initialized; call Init before use")
}

Prevention

Always construct the tracker via its constructor/Init, never a zero-value struct literal
Run Validate as part of application startup after Init
Check Init's error before proceeding to Validate or any API calls
Encode the Init→Validate→Execute lifecycle in a factory function so ordering cannot be skipped

When it happens

Trigger: Calling (&jira.Tracker{}).Validate(), calling Validate before Init, or calling Validate after Init returned an error and left the client unset.

Common situations: Wiring the tracker via dependency injection without invoking the constructor/Init; retry logic that ignores Init's error; tests constructing the struct literal directly; lifecycle ordering bugs where Validate runs before initialization.

Related errors

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