Linear authentication not configured Options: OAuth (for C

Error message

Linear authentication not configured
Options:
  OAuth (for CI):  export LINEAR_OAUTH_CLIENT_ID=... LINEAR_OAUTH_CLIENT_SECRET=...
  API key (devs):  export LINEAR_API_KEY=... or bd config set linear.api_key "YOUR_API_KEY"

What it means

Linear sync requires credentials: either OAuth client ID+secret (recommended for CI) or a Linear API key. validateLinearConfig checks config keys linear.oauth_client_id/secret and linear.api_key (which may themselves come from env vars LINEAR_OAUTH_CLIENT_ID/SECRET or LINEAR_API_KEY); if none are set it returns this multi-line guidance error.

Source

Thrown at cmd/bd/linear.go:1017

// validateLinearConfig checks that required Linear configuration is present.
// cliTeams is the list of team IDs from the --team flag (may be nil).
func validateLinearConfig(cliTeams []string) error {
	if err := ensureStoreActive(); err != nil {
		return fmt.Errorf("database not available: %w", err)
	}

	ctx := rootCtx

	// Accept either OAuth credentials or API key.
	oauthClientID, _ := getLinearConfig(ctx, "linear.oauth_client_id")
	oauthClientSecret, _ := getLinearConfig(ctx, "linear.oauth_client_secret")
	hasOAuth := oauthClientID != "" && oauthClientSecret != ""

	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

View on GitHub (pinned to 71377f2769)

Solutions

For CI: export LINEAR_OAUTH_CLIENT_ID and LINEAR_OAUTH_CLIENT_SECRET
For local dev: export LINEAR_API_KEY, or run `bd config set linear.api_key "YOUR_API_KEY"`
Verify with `bd config get linear.api_key` that the value persisted and the shell running bd actually has the env vars

Example fix

// before
$ bd linear pull
Error: Linear authentication not configured...
// after
$ export LINEAR_API_KEY=lin_api_xxx
$ bd linear pull

Defensive patterns

Strategy: validation

Validate before calling

func linearAuthReady() bool {
	hasOAuth := os.Getenv("LINEAR_OAUTH_CLIENT_ID") != "" && os.Getenv("LINEAR_OAUTH_CLIENT_SECRET") != ""
	if hasOAuth {
		return true
	}
	if k := os.Getenv("LINEAR_API_KEY"); k != "" {
		return true
	}
	return false
}

Try / catch

if err := runLinearPull(ctx); err != nil && strings.Contains(err.Error(), "Linear authentication not configured") {
	return fmt.Errorf("set LINEAR_API_KEY or OAuth vars before syncing: %w", err)
}

Prevention

Set credentials in shell profile or CI secret store before running linear commands
Remember OAuth requires BOTH client id and secret
Verify with `env | grep LINEAR` in the same shell/process running bd

When it happens

Trigger: Running bd linear sync/push/pull with no LINEAR_API_KEY env var, no LINEAR_OAUTH_CLIENT_ID/LINEAR_OAUTH_CLIENT_SECRET env vars, and no corresponding keys in bd config.

Common situations: Fresh setup where credentials were never configured; CI environment missing exported secrets; credentials stored under wrong config key names; shell profile not sourced in the CI job.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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