invalid Linear team ID (expected UUID format like '12345678-

Error message

invalid Linear team ID (expected UUID format like '12345678-1234-1234-1234-123456789abc')
Invalid value: %s

What it means

Linear team IDs must be UUIDs. validateLinearConfig iterates the resolved team IDs and validates each with isValidUUID; any ID not matching UUID format (e.g. a team name/key like 'ENG' or a truncated ID) produces this error naming the invalid value.

Source

Thrown at cmd/bd/linear.go:1031

	if !hasOAuth {
		apiKey, _ := getLinearConfig(ctx, "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\"")
		}
	}

	teamIDs := getLinearTeamIDs(ctx, cliTeams)
	if len(teamIDs) == 0 {
		return fmt.Errorf("no Linear team ID configured\nRun: bd config set linear.team_id \"TEAM_ID\"\nOr:  bd config set linear.team_ids \"TEAM_ID1,TEAM_ID2\"\nOr: export LINEAR_TEAM_ID=TEAM_ID")
	}

	for _, id := range teamIDs {
		if !isValidUUID(id) {
			return fmt.Errorf("invalid Linear team ID (expected UUID format like '12345678-1234-1234-1234-123456789abc')\nInvalid value: %s", id)
		}
	}

	return nil
}

// maskAPIKey returns a masked version of an API key for display.
// Shows first 4 and last 4 characters, with dots in between.
func maskAPIKey(key string) string {
	if len(key) <= 8 {
		return "****"
	}
	return key[:4] + "..." + key[len(key)-4:]
}

// getLinearConfig reads a Linear configuration value. Returns the value and its source.
// Priority: environment variable > project config.
// Env vars take precedence so CI workers can override config without modifying config.yaml.

View on GitHub (pinned to 71377f2769)

Solutions

Run `bd linear teams` to list teams with their correct UUIDs
Replace the configured value with the UUID, e.g. `bd config set linear.team_id "12345678-1234-1234-1234-123456789abc"`
Check for stray whitespace/quotes: `echo "[$LINEAR_TEAM_ID]"` and re-export cleanly

Example fix

// before
bd config set linear.team_id "ENG"
// after
bd config set linear.team_id "12345678-1234-1234-1234-123456789abc"

Defensive patterns

Strategy: validation

Validate before calling

var uuidRe = regexp.MustCompile(`^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$`)
if !uuidRe.MatchString(teamID) {
	return fmt.Errorf("team ID %q is not a UUID; get it from 'bd linear teams'", teamID)
}

Type guard

func isUUID(s string) bool {
	_, err := uuid.Parse(s)
	return err == nil
}

Try / catch

if err := runLinearPush(ctx); err != nil && strings.Contains(err.Error(), "invalid Linear team ID") {
	// re-fetch via `bd linear teams` and fix linear.team_id
}

Prevention

Copy the UUID from `bd linear teams`, not the team name or URL slug
Validate configured IDs with a UUID regex at setup time
Trim whitespace/quotes before saving config values

When it happens

Trigger: Setting linear.team_id / linear.team_ids or LINEAR_TEAM_ID (or passing --team) to a value like `ENG`, a Linear team URL slug, or a malformed string rather than the UUID-form team ID.

Common situations: User copied the team name or URL key instead of the UUID; pasted ID with whitespace or quotes; older integration stored non-UUID identifiers.

Related errors

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