gastownhall/beads · error

gate condition not satisfied: %s (use --force to override)

Error message

gate condition not satisfied: %s (use --force to override)

What it means

checkGateSatisfaction enforces that an issue with `await-type: bead` has had its gating bead (await-id) resolved before the issue can be closed. If checkBeadGate reports unresolved, close is blocked and the user is told to use --force to override.

Source

Thrown at cmd/bd/close.go:575

	var resolved bool
	var escalated bool
	var reason string
	var err error

	switch {
	case strings.HasPrefix(issue.AwaitType, "gh:run"):
		resolved, escalated, reason, err = checkGHRun(issue, func(gateID, runID string) error { return updateGateAwaitIDFunc(nil, gateID, runID) })
	case strings.HasPrefix(issue.AwaitType, "gh:pr"):
		resolved, escalated, reason, err = checkGHPR(issue)
	case issue.AwaitType == "timer":
		resolved, escalated, reason, err = checkTimer(issue, time.Now())
	case issue.AwaitType == "bead":
		resolved, reason = checkBeadGate(rootCtx, store, issue.AwaitID)
		if resolved {
			return nil
		}
		return fmt.Errorf("gate condition not satisfied: %s (use --force to override)", reason)
	}

	if err != nil {
		// If we can't check the condition, allow close with a warning
		fmt.Fprintf(os.Stderr, "Warning: could not evaluate gate condition: %v\n", err)
		return nil
	}

	if resolved {
		return nil
	}

	if escalated {
		return fmt.Errorf("gate condition not satisfied: %s (use --force to override)", reason)
	}

	return fmt.Errorf("gate condition not satisfied: %s (use --force to override)", reason)
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Close (or resolve) the gate bead referenced by the issue's await-id, then retry the close.
2. Re-run with `--force` if you intentionally want to close past the unsatisfied gate.
3. Check the gate with `bd show <gate-id>` to see why it is still unresolved.

Example fix

// before
bd close bd-42
// error: gate condition not satisfied: bd-7 still open
// after
close bd-7 first, or:
bd close bd-42 --force

bd show bd-42 | grep await-id   # then verify the gate bead is closed:
bd show <await-id> | grep -i status

func gateSatisfied(issue Issue, isClosed func(string) bool) bool {
	return issue.AwaitType != "bead" || isClosed(issue.AwaitID)
}

if err := checkGateSatisfaction(issue); err != nil {
	if strings.Contains(err.Error(), "gate condition not satisfied") {
		// close the gate bead first or retry with --force
	}
}

When it happens

Trigger: Running `bd close` on an issue whose AwaitType is "bead" and whose referenced gate bead (issue.AwaitID) is not yet closed/resolved.

Common situations: Closing a work item whose blocking dependency bead is still open; forgetting to close the gate bead first; deliberate early closure requiring --force.

Related errors

• failed to add supersede link: %w
• gh CLI not found: install from https://cli.github.com
• db: DependencySQLRepository.Insert: dep must not be nil
• db: DependencySQLRepository.Insert: IssueID must not be empt
• db: DependencySQLRepository.Insert: DependsOnID must not be

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