{"record":{"id":"c50d8cd6500726e6","repo":"gastownhall/beads","slug":"errcloseblocked","errorCode":"ErrCloseBlocked","errorMessage":"cannot close blocked issue","messagePattern":"cannot close blocked issue","errorType":"error_code","errorClass":null,"httpStatus":null,"severity":"error","filePath":"issueops/errors.go","lineNumber":104,"sourceCode":"// invalid, a row can be missing and a database can be uninitialized on any\n// plane. The refusals BELOW that name issue concepts stay here.\nvar (\n\t// ErrNotFound is returned when a requested entity does not exist in the database.\n\tErrNotFound = beadserrors.ErrNotFound\n\t// ErrValidation classifies deterministic request-validation failures.\n\tErrValidation = beadserrors.ErrValidation\n\t// ErrNotInitialized is returned when the database has not been initialized\n\t// (e.g., issue_prefix config is missing).\n\tErrNotInitialized = beadserrors.ErrNotInitialized\n)\n\n// ErrPrefixMismatch is returned when an issue ID does not match the configured prefix.\nvar ErrPrefixMismatch = errors.New(\"prefix mismatch\")\n\n// ErrCloseBlocked is returned by CloseIssueChecked when an issue cannot be\n// closed because it is still blocked (is_blocked=1: an open blocking dependency\n// or an open blocking gate). Bypass with CloseIssueOptions.Force.\nvar ErrCloseBlocked = errors.New(\"cannot close blocked issue\")\n\n// ErrCloseOpenChildren is returned when an unforced close finds open\n// parent-child dependents.\nvar ErrCloseOpenChildren = errors.New(\"cannot close issue with open children\")\n\n// CloseOpenChildrenError reports the issue and open-child count that refused a\n// guarded close.\ntype CloseOpenChildrenError struct {\n\tIssueID      string\n\tOpenChildren int\n}\n\nfunc (e *CloseOpenChildrenError) Error() string {\n\treturn fmt.Sprintf(\"cannot close %s: %d open child issue(s); close children first or use --force to override\", e.IssueID, e.OpenChildren)\n}\n\n// Unwrap makes CloseOpenChildrenError match ErrCloseOpenChildren.\nfunc (e *CloseOpenChildrenError) Unwrap() error {","sourceCodeStart":86,"sourceCodeEnd":122,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/issueops/errors.go#L86-L122","documentation":"ErrCloseBlocked is returned by CloseIssueChecked when an issue cannot be closed because it is still blocked: is_blocked=1 due to an open blocking dependency or an open blocking gate. Bypass with CloseIssueOptions.Force. Batch closer paths surface it as a per-item refusal while survivors commit.","triggerScenarios":"Calling CloseIssueChecked (or lifecycle close / batch close) on an issue with is_blocked=1; the issue has an open blocking dependency or an open blocking gate; transitively blocked targets in lifecycle close flows.","commonSituations":"Closing a parent/epic whose blocker children are still open; forgetting to finish dependency work first; batch scripts closing everything without checking dependency state; gates (external conditions) still open.","solutions":["Close or resolve the open blocking dependencies/gates first, then retry the close.","Pass CloseIssueOptions.Force = true to deliberately close the blocked issue.","Inspect the issue's dependencies (bd dep list) to find what is blocking it.","In batch closes, handle the per-item refusal and let survivors commit rather than failing the whole batch."],"exampleFix":"// before\nerr := ops.CloseIssueChecked(ctx, id, types.CloseIssueOptions{}) // blocked\n\n// after\nerr := ops.CloseIssueChecked(ctx, id, types.CloseIssueOptions{Force: true})\n// or resolve blockers first, then close without Force","handlingStrategy":"validation","validationCode":"iss, _ := store.GetIssue(ctx, id)\nif iss.IsBlocked {\n    // resolve open blocking dependencies/gates before closing\n}","typeGuard":null,"tryCatchPattern":"if errors.Is(err, issueops.ErrCloseBlocked) {\n    // list blockers for the user or retry with CloseIssueOptions.Force\n}","preventionTips":["Check is_blocked / dependency state before batch closes.","Close blocking children or resolve gates before parents.","Use Force only as a deliberate, audited bypass.","In batch closes, treat per-item refusals as results and let survivors commit."],"tags":["close","dependencies","blocked"],"backgroundTag":"cannot-close-blocked-issue","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}