linear.state_map is not configured. Run 'bd linear link' to

Error message

linear.state_map is not configured.
Run 'bd linear link' to configure status mapping first.

What it means

ValidatePushStateMappings refuses to run a Linear push when no explicit status mapping has been configured. The tracker requires an ExplicitStateMap so every beads status (open, in-progress, blocked, closed) can be translated to a concrete Linear workflow state before any mutation. Without it the push would be ambiguous, so it fails fast before touching Linear.

Source

Thrown at internal/linear/tracker.go:609

		return false
	}
	switch status {
	case types.StatusBlocked, types.StatusDeferred, types.StatusPinned, types.StatusHooked:
		return true
	}
	for _, cs := range custom {
		if types.Status(cs.Name) == status {
			return true
		}
	}
	return false
}

// ValidatePushStateMappings ensures push has explicit, non-ambiguous status
// mappings for every configured team before any mutation occurs.
func (t *Tracker) ValidatePushStateMappings(ctx context.Context) error {
	if t.config == nil || len(t.config.ExplicitStateMap) == 0 {
		return fmt.Errorf("%s", missingExplicitStateMapMessage)
	}
	statuses := []types.Status{
		types.StatusOpen,
		types.StatusInProgress,
		types.StatusBlocked,
		types.StatusClosed,
		types.StatusDeferred,
		types.StatusPinned,
		types.StatusHooked,
	}
	for _, teamID := range t.teamIDs {
		client := t.clients[teamID]
		if client == nil {
			continue
		}
		cache, err := BuildStateCache(ctx, client)
		if err != nil {
			return fmt.Errorf("fetching workflow states for team %s: %w", teamID, err)

View on GitHub (pinned to 71377f2769)

Solutions

Run 'bd linear link' to configure the status mapping before syncing/pushing.
Add an explicit state_map (status → Linear workflow state) for each configured team in the Linear config.
Verify the config loaded by the tracker actually populates config.ExplicitStateMap (check the config path and team list).

Example fix

// before
tracker.ValidatePushStateMappings(ctx) // fails: state_map not configured
// after
// $ bd linear link   # writes explicit state_map
tracker.ValidatePushStateMappings(ctx)

Defensive patterns

Strategy: validation

Validate before calling

if tracker == nil || tracker.Config() == nil || len(tracker.Config().ExplicitStateMap) == 0 {
    return fmt.Errorf("run 'bd linear link' before pushing to Linear")
}

Type guard

func hasStateMap(cfg *linear.Config) bool { return cfg != nil && len(cfg.ExplicitStateMap) > 0 }

Try / catch

if err := tracker.ValidatePushStateMappings(ctx); err != nil {
    if strings.Contains(err.Error(), "not configured") { /* prompt user to run bd linear link */ }
    return err
}

Prevention

Run 'bd linear link' as part of environment setup.
Keep the Linear config in version control so state_map ships with the repo.
Validate config at startup before any sync command.

When it happens

Trigger: Calling Tracker.ValidatePushStateMappings (directly or via runLinearSync / runLinearPush) when t.config is nil or t.config.ExplicitStateMap is empty — i.e. 'bd linear link' has never been run or the state_map section is absent from the Linear config.

Common situations: Fresh checkout or new machine where the Linear integration was never linked; config file present but the status-mapping block removed by hand; upgrading from an older bd version that mapped statuses implicitly.

Related errors

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