What causes "Linear team ID not configured" in gastownhall/beads?

Persist the team: `bd config set linear.team_id "TEAM_UUID"`

Linear team ID not configured

Error message

Linear team ID not configured

What it means

getLinearClient resolves team IDs using only configuration (no CLI flags are passed — cliTeams is nil). If no team ID is configured anywhere, it refuses to build a client and returns this short error.

Source

Thrown at cmd/bd/linear.go:1134

// Precedence: cliTeams (--team flag) > linear.team_ids > LINEAR_TEAM_IDS > linear.team_id > LINEAR_TEAM_ID
func getLinearTeamIDs(ctx context.Context, cliTeams []string) []string {
	pluralVal, _ := getLinearConfig(ctx, "linear.team_ids")
	singularVal, _ := getLinearConfig(ctx, "linear.team_id")
	return tracker.ResolveProjectIDs(cliTeams, pluralVal, singularVal)
}

// getLinearClient creates a configured Linear client from beads config.
// Uses the first configured team ID for operations that require a single team.
//
// Auth precedence:
//  1. OAuth env vars (LINEAR_OAUTH_CLIENT_ID + LINEAR_OAUTH_CLIENT_SECRET)
//  2. LINEAR_API_KEY env var
//  3. linear.oauth_client_id + linear.oauth_client_secret in config
//  4. linear.api_key in config
func getLinearClient(ctx context.Context) (*linear.Client, error) {
	teamIDs := getLinearTeamIDs(ctx, nil)
	if len(teamIDs) == 0 {
		return nil, fmt.Errorf("Linear team ID not configured")
	}

	client, err := buildLinearClient(ctx, teamIDs[0])
	if err != nil {
		return nil, err
	}

	if store != nil {
		if endpoint, _ := store.GetConfig(ctx, "linear.api_endpoint"); endpoint != "" {
			client = client.WithEndpoint(endpoint)
		}
		if projectID, _ := store.GetConfig(ctx, "linear.project_id"); projectID != "" {
			client = client.WithProjectID(projectID)
		}
		// Apply optional rate-limit circuit-breaker floor.
		// Readable/settable via `bd config get/set linear.rate_limit_floor`.
		// Also honored via the LINEAR_RATE_LIMIT_FLOOR environment variable.
		floorStr, _ := getLinearConfig(ctx, "linear.rate_limit_floor")

View on GitHub (pinned to 71377f2769)

Solutions

Persist the team: `bd config set linear.team_id "TEAM_UUID"`
Or set LINEAR_TEAM_ID in the environment of the process calling getLinearClient (e.g. the daemon)
For multiple teams use `bd config set linear.team_ids "ID1,ID2"`

Example fix

// before
client, err := getLinearClient(ctx) // Error: Linear team ID not configured
// after
// run once first:
// bd config set linear.team_id "12345678-1234-1234-1234-123456789abc"
client, err := getLinearClient(ctx)

Defensive patterns

Strategy: validation

Validate before calling

ids := getLinearTeamIDs(ctx, nil)
if len(ids) == 0 {
	return errors.New("persist linear.team_id before invoking operations that build a Linear client")
}

Try / catch

client, err := getLinearClient(ctx)
if err != nil && strings.Contains(err.Error(), "team ID not configured") {
	// set LINEAR_TEAM_ID in the daemon environment or bd config, retry
}

Prevention

Persist team ID in bd config rather than relying on ephemeral CLI flags
Ensure daemon processes inherit LINEAR_TEAM_ID if env-based config is used
Run `bd linear teams` once during onboarding and record the UUID

When it happens

Trigger: Any code path calling getLinearClient (e.g. background/daemon Linear operations, commands without --team) when linear.team_id/linear.team_ids config and LINEAR_TEAM_ID env are all unset.

Common situations: Daemon-driven sync where the CLI flag from an interactive command isn't available; environment where only the API key was configured but the team was never persisted.

Related errors

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