What causes "start must be >= 1" in gastownhall/beads?

Pass a 1-based start: use `--range 1-5` instead of `--range 0-5`.

start must be >= 1

Error message

start must be >= 1

What it means

`parseRange` in `bd mol current` validates the user-supplied step range (e.g. `--steps 3-7`). It parses both endpoints with `strconv.Atoi` and then enforces that the start of a 1-based inclusive range is at least 1. Because molecule steps are numbered from 1, a start of 0 or negative is meaningless, so the command refuses it instead of silently clipping.

Source

Thrown at cmd/bd/mol_current.go:704

}

// parseRange parses a range string like "1-50" or "100-150" into start and end indices.
// Returns 1-based indices (start=1 means first step).
func parseRange(rangeStr string) (start, end int, err error) {
	parts := strings.Split(rangeStr, "-")
	if len(parts) != 2 {
		return 0, 0, fmt.Errorf("expected format 'start-end' (e.g., '1-50')")
	}
	start, err = strconv.Atoi(strings.TrimSpace(parts[0]))
	if err != nil {
		return 0, 0, fmt.Errorf("invalid start: %w", err)
	}
	end, err = strconv.Atoi(strings.TrimSpace(parts[1]))
	if err != nil {
		return 0, 0, fmt.Errorf("invalid end: %w", err)
	}
	if start < 1 {
		return 0, 0, fmt.Errorf("start must be >= 1")
	}
	if end < start {
		return 0, 0, fmt.Errorf("end must be >= start")
	}
	return start, end, nil
}

// filterStepsByRange filters steps to a 1-based range [start, end].
func filterStepsByRange(steps []*StepStatus, start, end int) []*StepStatus {
	// Convert to 0-based indices
	startIdx := start - 1
	endIdx := end

	if startIdx >= len(steps) {
		return nil
	}
	if endIdx > len(steps) {
		endIdx = len(steps)

View on GitHub (pinned to 71377f2769)

Solutions

Pass a 1-based start: use `--range 1-5` instead of `--range 0-5`.
If the value comes from a script, add 1 when converting from zero-based indices before invoking the command.
When no step numbering is known, omit the range flag entirely to show all current steps instead of guessing a lower bound.

Example fix

// before
bd mol current --range 0-5
// after
bd mol current --range 1-5

Defensive patterns

Strategy: validation

Validate before calling

// shell: validate range before invoking bd
if [[ "$RANGE" =~ ^([0-9]+)-([0-9]+)$ ]]; then
  START=${BASH_REMATCH[1]}; END=${BASH_REMATCH[2]}
  (( START >= 1 && END >= START )) || { echo "range must be N-M with N>=1, M>=N"; exit 1; }
fi
bd mol current --range "$START-$END"

Type guard

func validRange(s, e int) bool { return s >= 1 && e >= s }

Prevention

Treat molecule step ranges as 1-based everywhere in scripts.
Convert zero-based counters with i+1 before building a range string.
Omit the range flag when unsure instead of guessing bounds.

When it happens

Trigger: Running `bd mol current` (or the proxied-server equivalent `runMolCurrentProxiedServer`) with a step range whose left side is 0 or negative, e.g. `--range 0-5` or `--range -2-4`. The message surfaces from the `if start < 1` check in `parseRange` after `strconv.Atoi` succeeds.

Common situations: Scripts that compute a range from a zero-based counter and pass it straight through (off-by-one, `i` starting at 0); users assuming ranges are 0-based like array indices; automation emitting `0-N` when no step has started yet.

Related errors

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