{"record":{"id":"06ab0f0655e972ff","repo":"gastownhall/beads","slug":"creating-linear-milestone-epic-q-w","errorCode":null,"errorMessage":"creating Linear milestone epic %q: %w","messagePattern":"creating Linear milestone epic %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/linear.go","lineNumber":642,"sourceCode":"\t}\n\n\texternalRef := ref\n\tepic := &types.Issue{\n\t\tTitle:       title,\n\t\tDescription: description,\n\t\tStatus:      types.StatusOpen,\n\t\tPriority:    2,\n\t\tIssueType:   types.TypeEpic,\n\t\tExternalRef: &externalRef,\n\t\tMetadata:    metadata,\n\t}\n\tif generateID != nil {\n\t\tif err := generateID(ctx, epic); err != nil {\n\t\t\treturn \"\", fmt.Errorf(\"generating Linear milestone epic ID: %w\", err)\n\t\t}\n\t}\n\tif err := st.CreateIssue(ctx, epic, actor); err != nil {\n\t\treturn \"\", fmt.Errorf(\"creating Linear milestone epic %q: %w\", title, err)\n\t}\n\treturn ref, nil\n}\n\nfunc findLinearMilestoneEpic(ctx context.Context, st storage.Storage, ref, milestoneID, title string) (*types.Issue, error) {\n\tif existing, err := st.GetIssueByExternalRef(ctx, ref); err == nil {\n\t\treturn existing, nil\n\t} else if !errors.Is(err, storage.ErrNotFound) {\n\t\treturn nil, err\n\t}\n\n\tissues, err := st.SearchIssues(ctx, \"\", types.IssueFilter{})\n\tif err != nil {\n\t\treturn nil, fmt.Errorf(\"searching local issues for Linear milestone %s: %w\", milestoneID, err)\n\t}\n\tfor _, issue := range issues {\n\t\tif issueHasLinearMilestoneID(issue, milestoneID) {\n\t\t\treturn issue, nil","sourceCodeStart":624,"sourceCodeEnd":660,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/linear.go#L624-L660","documentation":"Wraps st.CreateIssue failures when persisting a new Linear milestone epic. The epic (type epic, external ref set, merged metadata) failed to be written to storage; the error includes the epic title and root cause via %w.","triggerScenarios":"ensureLinearMilestoneEpic found no existing epic for the milestone external ref and attempted creation; storage rejects the write — duplicate external ref race, DB unavailable, validation failure on the issue payload.","commonSituations":"Two concurrent syncs both creating the same milestone epic (unique-constraint race); database locked/offline; invalid characters in title from Linear flowing into storage constraints.","solutions":["Check the wrapped storage error; if it's a duplicate/uniqueness failure, re-run the sync — it will find the existing epic via GetIssueByExternalRef","Ensure only one sync runs per workspace at a time","Verify database connectivity and retry"],"exampleFix":null,"handlingStrategy":"retry","validationCode":"// avoid duplicate-create races by checking the ref first\nif _, err := st.GetIssueByExternalRef(ctx, externalRef); err == nil {\n    return \"\", nil // epic already exists; skip create\n}","typeGuard":null,"tryCatchPattern":"if err := st.CreateIssue(ctx, epic, actor); err != nil {\n    if isDuplicate(err) { return findLinearMilestoneEpic(ctx, st, ref, milestoneID, title) }\n    return \"\", fmt.Errorf(\"creating Linear milestone epic %q: %w\", title, err)\n}","preventionTips":["Serialize syncs per workspace to avoid create races on the same external ref","Treat duplicate-key failures as success-by-another-path and re-lookup","Confirm database connectivity before import runs"],"tags":["linear","storage","create-issue","sync"],"backgroundTag":"issue-create-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}