{"record":{"id":"660d77c296a4a33c","repo":"gastownhall/beads","slug":"linear-state-map-has-no-configured-linear-state-fo","errorCode":null,"errorMessage":"linear.state_map has no configured Linear state for beads status %q","messagePattern":"linear\\.state_map has no configured Linear state for beads status %q","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/linear/mapping.go","lineNumber":434,"sourceCode":"\tvar typeMatches []State\n\tfor _, state := range cache.States {\n\t\tmapped, ok := config.ExplicitStateMap[strings.ToLower(strings.TrimSpace(state.Type))]\n\t\tif ok && stateMapMatchesStatus(mapped, status) {\n\t\t\ttypeMatches = append(typeMatches, state)\n\t\t}\n\t}\n\tif len(typeMatches) == 1 {\n\t\treturn typeMatches[0].ID, nil\n\t}\n\tif len(typeMatches) > 1 {\n\t\tnames := make([]string, 0, len(typeMatches))\n\t\tfor _, state := range typeMatches {\n\t\t\tnames = append(names, state.Name)\n\t\t}\n\t\treturn \"\", fmt.Errorf(\"linear.state_map type fallback is ambiguous for beads status %q across Linear states: %s. Set linear.outbound_state_map.%s = \\\"<state name>\\\" to disambiguate\", status, strings.Join(names, \", \"), status)\n\t}\n\n\treturn \"\", fmt.Errorf(\"linear.state_map has no configured Linear state for beads status %q\", status)\n}\n\n// ParseBeadsStatus converts a status string to types.Status.\nfunc ParseBeadsStatus(s string) types.Status {\n\tswitch strings.ToLower(s) {\n\tcase \"open\":\n\t\treturn types.StatusOpen\n\tcase \"in_progress\", \"in-progress\", \"inprogress\":\n\t\treturn types.StatusInProgress\n\tcase \"blocked\":\n\t\treturn types.StatusBlocked\n\tcase \"closed\", \"done\":\n\t\treturn types.StatusClosed\n\tcase \"deferred\":\n\t\treturn types.StatusDeferred\n\tcase \"pinned\":\n\t\treturn types.StatusPinned\n\tcase \"hooked\":","sourceCodeStart":416,"sourceCodeEnd":452,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/linear/mapping.go#L416-L452","documentation":"After explicit name matching and the type fallback both fail, ResolveStateIDForBeadsStatus gives up with this error: the configured linear.state_map has no entry that matches any Linear state for the beads status being pushed. The push cannot proceed without knowing which Linear state to move the issue to.","triggerScenarios":"Calling ResolveStateIDForBeadsStatus where no state name and no state type in the cache has a linear.state_map entry matching the given types.Status — e.g. config only maps 'open' but the status being pushed is 'in_progress'.","commonSituations":"Partial state_map configuration covering only some statuses; pushing a newly introduced beads status that was never mapped; typos in the status key on the left side of state_map.","solutions":["Add a linear.state_map entry for the missing beads status (by Linear state name or type).","Run 'bd linear link' to regenerate a complete status mapping.","Check the status key spelling on the left side of linear.state_map (use lowercase beads statuses: open, in_progress, closed).","Verify which status is actually being pushed (log it) and confirm it is one you intended to map."],"exampleFix":"// before\n[linear.state_map]\nopen = \"Backlog\"   # in_progress not mapped\n// after\n[linear.state_map]\nopen = \"Backlog\"\nin_progress = \"In Progress\"\nclosed = \"Done\"","handlingStrategy":"validation","validationCode":"func validateAllStatusesMapped(cfg *linear.MappingConfig, cache *linear.StateCache, statuses []types.Status) error {\n\tfor _, st := range statuses {\n\t\tif _, err := linear.ResolveStateIDForBeadsStatus(cache, st, cfg); err != nil {\n\t\t\treturn fmt.Errorf(\"status %s not mapped for push: %w\", st, err)\n\t\t}\n\t}\n\treturn nil\n}","typeGuard":null,"tryCatchPattern":"stateID, err := linear.ResolveStateIDForBeadsStatus(cache, status, cfg)\nif err != nil && strings.Contains(err.Error(), \"no configured Linear state\") {\n\treturn fmt.Errorf(\"status %q is not mapped; add it to [linear.state_map] or run 'bd linear link'\", status)\n}","preventionTips":["Map every beads status your team uses (open, in_progress, closed) in linear.state_map.","Run 'bd linear link' after adding new statuses or states.","Validate the full status set at startup, not per-push.","Check for typos in status keys (lowercase, snake_case).","When introducing a new beads status, update the Linear mapping in the same change."],"tags":["linear","configuration","state-mapping","push"],"backgroundTag":"unmapped-status","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}