gastownhall/beads · error

no labels connection found for team

Error message

no labels connection found for team

What it means

GetTeamLabels expects every page response to contain a non-nil `team.labels` connection. If the field decodes as nil (missing from the response), the client treats it as an unusable response and returns this error instead of silently returning zero labels.

Source

Thrown at internal/linear/client.go:717

			return nil, fmt.Errorf("failed to fetch team labels: %w", err)
		}

		var page struct {
			Team struct {
				Labels *struct {
					Nodes    []Label `json:"nodes"`
					PageInfo struct {
						HasNextPage bool   `json:"hasNextPage"`
						EndCursor   string `json:"endCursor"`
					} `json:"pageInfo"`
				} `json:"labels"`
			} `json:"team"`
		}
		if err := json.Unmarshal(data, &page); err != nil {
			return nil, fmt.Errorf("failed to parse team labels response: %w", err)
		}
		if page.Team.Labels == nil {
			return nil, fmt.Errorf("no labels connection found for team")
		}

		all = append(all, page.Team.Labels.Nodes...)
		if !page.Team.Labels.PageInfo.HasNextPage {
			break
		}
		if page.Team.Labels.PageInfo.EndCursor == "" {
			break
		}
		cursor := page.Team.Labels.PageInfo.EndCursor
		after = &cursor
	}

	return all, nil
}

// FindIssueByDescriptionContains searches for an issue whose description
// contains the given text. This powers idempotency dedup: we embed a

View on GitHub (pinned to 71377f2769)

Solutions

1. Validate the team ID against `viewer.teams` or `teams { nodes { id name } }` using the same API key.
2. Inspect the response for a GraphQL `errors` array and propagate it, which usually explains why `labels` is null.
3. Check Linear API schema for renames (e.g. `issueLabels`) and update the query and struct.
4. Regenerate the API key with the correct scopes/team access.

Example fix

// before
if page.Team.Labels == nil {
    return nil, fmt.Errorf("no labels connection found for team")
}
// after
if page.Team.Labels == nil {
    return nil, fmt.Errorf("no labels connection found for team (verify team ID and API key scopes)")
}

// resolve and verify the team before building caches
teams, err := client.GetTeams(ctx)
if err != nil || len(teams) == 0 {
    return errors.New("no accessible Linear teams for this API key")
}
// use teams[i].Id when initializing the client

func labelsPresent(page struct{ Team struct{ Labels *struct{} } }) bool {
    return page.Team.Labels != nil
}

labels, err := client.GetTeamLabels(ctx)
if err != nil {
    if strings.Contains(err.Error(), "no labels connection") {
        log.Printf("team %s has no accessible labels; skipping label cache", teamID)
        return nil // degrade gracefully
    }
    return err
}

When it happens

Trigger: The GraphQL response omits data.team.labels entirely — team ID doesn't exist or isn't accessible with this key, GraphQL errors returned with partial data (error object present, labels absent), or the labels connection was renamed in a schema update.

Common situations: Misconfigured team ID (env var pointing to the wrong workspace), API key scoped without label read access, Linear schema rename of `labels`, intermittent GraphQL partial-error responses.

Related errors

• no states found for team
• issue creation reported as unsuccessful
• failed to marshal request: %w
• failed to fetch team states: %w
• failed to fetch team labels: %w

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