{"record":{"id":"b2cd1160760261c2","repo":"gastownhall/beads","slug":"invalid-linear-team-id-expected-uuid-format-like","errorCode":null,"errorMessage":"invalid Linear team ID (expected UUID format like '12345678-1234-1234-1234-123456789abc')\nInvalid value: %s","messagePattern":"invalid Linear team ID \\(expected UUID format like '12345678-1234-1234-1234-123456789abc'\\)\nInvalid value: (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/linear.go","lineNumber":1031,"sourceCode":"\n\tif !hasOAuth {\n\t\tapiKey, _ := getLinearConfig(ctx, \"linear.api_key\")\n\t\tif apiKey == \"\" {\n\t\t\treturn fmt.Errorf(\"Linear authentication not configured\\n\" +\n\t\t\t\t\"Options:\\n\" +\n\t\t\t\t\"  OAuth (for CI):  export LINEAR_OAUTH_CLIENT_ID=... LINEAR_OAUTH_CLIENT_SECRET=...\\n\" +\n\t\t\t\t\"  API key (devs):  export LINEAR_API_KEY=... or bd config set linear.api_key \\\"YOUR_API_KEY\\\"\")\n\t\t}\n\t}\n\n\tteamIDs := getLinearTeamIDs(ctx, cliTeams)\n\tif len(teamIDs) == 0 {\n\t\treturn 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\")\n\t}\n\n\tfor _, id := range teamIDs {\n\t\tif !isValidUUID(id) {\n\t\t\treturn fmt.Errorf(\"invalid Linear team ID (expected UUID format like '12345678-1234-1234-1234-123456789abc')\\nInvalid value: %s\", id)\n\t\t}\n\t}\n\n\treturn nil\n}\n\n// maskAPIKey returns a masked version of an API key for display.\n// Shows first 4 and last 4 characters, with dots in between.\nfunc maskAPIKey(key string) string {\n\tif len(key) <= 8 {\n\t\treturn \"****\"\n\t}\n\treturn key[:4] + \"...\" + key[len(key)-4:]\n}\n\n// getLinearConfig reads a Linear configuration value. Returns the value and its source.\n// Priority: environment variable > project config.\n// Env vars take precedence so CI workers can override config without modifying config.yaml.","sourceCodeStart":1013,"sourceCodeEnd":1049,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/linear.go#L1013-L1049","documentation":"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.","triggerScenarios":"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.","commonSituations":"User copied the team name or URL key instead of the UUID; pasted ID with whitespace or quotes; older integration stored non-UUID identifiers.","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"],"exampleFix":"// before\nbd config set linear.team_id \"ENG\"\n// after\nbd config set linear.team_id \"12345678-1234-1234-1234-123456789abc\"","handlingStrategy":"validation","validationCode":"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}$`)\nif !uuidRe.MatchString(teamID) {\n\treturn fmt.Errorf(\"team ID %q is not a UUID; get it from 'bd linear teams'\", teamID)\n}","typeGuard":"func isUUID(s string) bool {\n\t_, err := uuid.Parse(s)\n\treturn err == nil\n}","tryCatchPattern":"if err := runLinearPush(ctx); err != nil && strings.Contains(err.Error(), \"invalid Linear team ID\") {\n\t// re-fetch via `bd linear teams` and fix linear.team_id\n}","preventionTips":["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"],"tags":["validation","uuid","linear","configuration"],"backgroundTag":"invalid-identifier-format","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}