{"record":{"id":"a7d723dc11643054","repo":"gastownhall/beads","slug":"linear-state-map-is-not-configured-run-bd-linear","errorCode":null,"errorMessage":"linear.state_map is not configured.\nRun 'bd linear link' to configure status mapping first.","messagePattern":"linear\\.state_map is not configured\\.\nRun 'bd linear link' to configure status mapping first\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/linear/tracker.go","lineNumber":609,"sourceCode":"\t\treturn false\n\t}\n\tswitch status {\n\tcase types.StatusBlocked, types.StatusDeferred, types.StatusPinned, types.StatusHooked:\n\t\treturn true\n\t}\n\tfor _, cs := range custom {\n\t\tif types.Status(cs.Name) == status {\n\t\t\treturn true\n\t\t}\n\t}\n\treturn false\n}\n\n// ValidatePushStateMappings ensures push has explicit, non-ambiguous status\n// mappings for every configured team before any mutation occurs.\nfunc (t *Tracker) ValidatePushStateMappings(ctx context.Context) error {\n\tif t.config == nil || len(t.config.ExplicitStateMap) == 0 {\n\t\treturn fmt.Errorf(\"%s\", missingExplicitStateMapMessage)\n\t}\n\tstatuses := []types.Status{\n\t\ttypes.StatusOpen,\n\t\ttypes.StatusInProgress,\n\t\ttypes.StatusBlocked,\n\t\ttypes.StatusClosed,\n\t\ttypes.StatusDeferred,\n\t\ttypes.StatusPinned,\n\t\ttypes.StatusHooked,\n\t}\n\tfor _, teamID := range t.teamIDs {\n\t\tclient := t.clients[teamID]\n\t\tif client == nil {\n\t\t\tcontinue\n\t\t}\n\t\tcache, err := BuildStateCache(ctx, client)\n\t\tif err != nil {\n\t\t\treturn fmt.Errorf(\"fetching workflow states for team %s: %w\", teamID, err)","sourceCodeStart":591,"sourceCodeEnd":627,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/linear/tracker.go#L591-L627","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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)."],"exampleFix":"// before\ntracker.ValidatePushStateMappings(ctx) // fails: state_map not configured\n// after\n// $ bd linear link   # writes explicit state_map\ntracker.ValidatePushStateMappings(ctx)","handlingStrategy":"validation","validationCode":"if tracker == nil || tracker.Config() == nil || len(tracker.Config().ExplicitStateMap) == 0 {\n    return fmt.Errorf(\"run 'bd linear link' before pushing to Linear\")\n}","typeGuard":"func hasStateMap(cfg *linear.Config) bool { return cfg != nil && len(cfg.ExplicitStateMap) > 0 }","tryCatchPattern":"if err := tracker.ValidatePushStateMappings(ctx); err != nil {\n    if strings.Contains(err.Error(), \"not configured\") { /* prompt user to run bd linear link */ }\n    return err\n}","preventionTips":["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."],"tags":["linear","configuration","status-mapping"],"backgroundTag":"missing-configuration","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}