Linear team ID not configured (set linear.team_id, linear.te

Error message

Linear team ID not configured (set linear.team_id, linear.team_ids, or LINEAR_TEAM_ID)

What it means

After authentication, Tracker.Init resolves which Linear team(s) to sync. It uses team IDs set via SetTeamIDs (CLI --team flag) if present; otherwise it reads linear.team_ids / LINEAR_TEAM_IDS and linear.team_id / LINEAR_TEAM_ID and passes them through ResolveProjectIDs. If the resolved list is empty, Init fails with this error and no clients are created.

Source

Thrown at internal/linear/tracker.go:69

	var apiKey string
	if !hasOAuth {
		apiKey, _ = t.getConfig(ctx, "linear.api_key", "LINEAR_API_KEY")
		if apiKey == "" {
			return fmt.Errorf("Linear authentication not configured\n" +
				"Options:\n" +
				"  OAuth (for CI):  export LINEAR_OAUTH_CLIENT_ID=... LINEAR_OAUTH_CLIENT_SECRET=...\n" +
				"  API key (devs):  export LINEAR_API_KEY=... or bd config set linear.api_key \"YOUR_API_KEY\"")
		}
	}

	// Resolve team IDs: use pre-set IDs (from CLI), or fall back to config.
	if len(t.teamIDs) == 0 {
		pluralVal, _ := t.getConfig(ctx, "linear.team_ids", "LINEAR_TEAM_IDS")
		singularVal, _ := t.getConfig(ctx, "linear.team_id", "LINEAR_TEAM_ID")
		t.teamIDs = tracker.ResolveProjectIDs(nil, pluralVal, singularVal)
		if len(t.teamIDs) == 0 {
			return fmt.Errorf("Linear team ID not configured (set linear.team_id, linear.team_ids, or LINEAR_TEAM_ID)")
		}
	}

	// Read optional endpoint and project ID.
	var endpoint, projectID string
	if store != nil {
		endpoint, _ = store.GetConfig(ctx, "linear.api_endpoint")
		projectID, _ = store.GetConfig(ctx, "linear.project_id")
		if projectID != "" {
			t.projectID = projectID
		}
	}

	// Read optional rate-limit floor (LINEAR_RATE_LIMIT_FLOOR env or linear.rate_limit_floor config).
	var rateLimitFloor int
	if floorStr, _ := t.getConfig(ctx, "linear.rate_limit_floor", "LINEAR_RATE_LIMIT_FLOOR"); floorStr != "" {
		if v, err := strconv.Atoi(strings.TrimSpace(floorStr)); err == nil && v >= 0 {
			rateLimitFloor = v

View on GitHub (pinned to 71377f2769)

Solutions

Set the team key: `bd config set linear.team_id "TEAM_KEY"` or export LINEAR_TEAM_ID=TEAM_KEY
For multiple teams, set linear.team_ids (comma-separated) or LINEAR_TEAM_IDS
Or pass the team explicitly on the command line with --team
Verify with `bd config get linear.team_id` that the value resolves and has no typos

Example fix

// before
export LINEAR_API_KEY=lin_api_xxx
// after: add team config
export LINEAR_API_KEY=lin_api_xxx
export LINEAR_TEAM_ID=ENG
# or multiple teams
export LINEAR_TEAM_IDS=ENG,OPS

Defensive patterns

Strategy: validation

Validate before calling

// Pre-flight: team must be configured before invoking tracker commands
if os.Getenv("LINEAR_TEAM_ID") == "" && os.Getenv("LINEAR_TEAM_IDS") == "" {
    return fmt.Errorf("set linear.team_id / linear.team_ids or pass --team")
}

Try / catch

if err := tr.Init(ctx, store); err != nil {
    if strings.Contains(err.Error(), "team ID not configured") {
        fmt.Fprintln(os.Stderr, "Run: bd config set linear.team_id <TEAM_KEY> (or export LINEAR_TEAM_ID)")
        os.Exit(2)
    }
    return err
}

Prevention

Configure linear.team_id (or team_ids) once per workspace via bd config set
Prefer the --team CLI flag for one-off runs to bypass config
In CI, export LINEAR_TEAM_ID alongside credentials
Verify config resolution with bd config get linear.team_id before debugging deeper

When it happens

Trigger: Calling Init with no --team flag and none of linear.team_id, linear.team_ids, LINEAR_TEAM_ID, LINEAR_TEAM_IDS set to a non-empty value.

Common situations: New workspace where the team key was never configured; CI environment lacking LINEAR_TEAM_ID; setting the value under the wrong config prefix (e.g. team_id without the linear. prefix); passing only LINEAR_TEAM_IDS where the config loader expected singular (or vice versa) with the other empty.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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