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

Tracker.Init for the Linear integration requires credentials: either OAuth client credentials (linear.oauth_client_id + linear.oauth_client_secret, or LINEAR_OAUTH_* env vars) or an API key (linear.api_key config / config.yaml, or LINEAR_API_KEY env). If neither is present, Init returns this multi-line error listing both options and no clients are created.

Source

Thrown at internal/linear/tracker.go:56

}

func (t *Tracker) Name() string         { return "linear" }
func (t *Tracker) DisplayName() string  { return "Linear" }
func (t *Tracker) ConfigPrefix() string { return "linear" }

func (t *Tracker) Init(ctx context.Context, store storage.Storage) error {
	t.store = store

	// Resolve authentication: OAuth client-credentials takes precedence over API key.
	oauthClientID, _ := t.getConfig(ctx, "linear.oauth_client_id", "LINEAR_OAUTH_CLIENT_ID")
	oauthClientSecret, _ := t.getConfig(ctx, "linear.oauth_client_secret", "LINEAR_OAUTH_CLIENT_SECRET")
	hasOAuth := oauthClientID != "" && oauthClientSecret != ""

	var apiKey string
	if !hasOAuth {
		apiKey, _ = t.getConfig(ctx, "linear.api_key", "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\"")
		}
	}

	// Resolve team IDs: use pre-set IDs (from CLI), or fall back to config.
	if len(t.teamIDs) == 0 {
		pluralVal, _ := t.getConfig(ctx, "linear.team_ids", "LINEAR_TEAM_IDS")
		singularVal, _ := t.getConfig(ctx, "linear.team_id", "LINEAR_TEAM_ID")
		t.teamIDs = tracker.ResolveProjectIDs(nil, pluralVal, singularVal)
		if len(t.teamIDs) == 0 {
			return fmt.Errorf("Linear team ID not configured (set linear.team_id, linear.team_ids, or LINEAR_TEAM_ID)")
		}
	}

	// Read optional endpoint and project ID.
	var endpoint, projectID string

View on GitHub (pinned to 71377f2769)

Solutions

Set an API key: `bd config set linear.api_key "YOUR_API_KEY"` or export LINEAR_API_KEY
For CI, configure OAuth: export LINEAR_OAUTH_CLIENT_ID and LINEAR_OAUTH_CLIENT_SECRET
Verify env vars are actually visible to the bd process (e.g. `bd config get linear.api_key`, `echo $LINEAR_API_KEY`)
Check for typos in variable names and that you run bd from the workspace whose config.yaml holds the key

Example fix

// before: env var typo, nothing set
export LINEAR_APIKEY=lin_api_xxx
// after
export LINEAR_API_KEY=lin_api_xxx
# or persist it
bd config set linear.api_key "lin_api_xxx"

Defensive patterns

Strategy: validation

Validate before calling

// Fail fast with a clear message before running tracker commands
if os.Getenv("LINEAR_API_KEY") == "" &&
    (os.Getenv("LINEAR_OAUTH_CLIENT_ID") == "" || os.Getenv("LINEAR_OAUTH_CLIENT_SECRET") == "") {
    return fmt.Errorf("Linear credentials missing: set LINEAR_API_KEY or LINEAR_OAUTH_CLIENT_ID/SECRET")
}

Try / catch

if err := tr.Init(ctx, store); err != nil {
    if strings.Contains(err.Error(), "authentication not configured") {
        fmt.Fprintln(os.Stderr, "Run: bd config set linear.api_key <key>  (or export LINEAR_API_KEY)")
        os.Exit(2)
    }
    return err
}

Prevention

Store the API key persistently: bd config set linear.api_key (kept in config.yaml, not the pushed DB)
In CI, inject LINEAR_OAUTH_CLIENT_ID/SECRET or LINEAR_API_KEY as secrets
Double-check env var spelling (LINEAR_API_KEY, not LINEAR_APIKEY/TOKEN)
Run bd from the workspace whose config.yaml actually contains the key

When it happens

Trigger: Calling Init (e.g. via `bd linear sync` or any linear tracker command) when: both LINEAR_OAUTH_CLIENT_ID and LINEAR_OAUTH_CLIENT_SECRET are unset, and neither `bd config set linear.api_key`/config.yaml nor LINEAR_API_KEY provides a value.

Common situations: Fresh clone without onboarding config; CI job where secrets were not injected into env; API key stored in config.yaml but running from a different working directory so yaml is not found; typo'd env var name (LINEAR_APIKEY, LINEAR_API_TOKEN).

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/7f31e1c1de843f34. Report an issue: GitHub.