--offset is not supported with hierarchical --parent + prett

Error message

--offset is not supported with hierarchical --parent + pretty/tree

What it means

In proxied mode, the hierarchical --parent walk with pretty/tree output does not implement pagination offsets. If --offset > 0 is passed alongside --parent with pretty output, this guard rejects the combination explicitly rather than silently ignoring the offset.

Source

Thrown at cmd/bd/list_proxied_server.go:63

	if err != nil {
		return nil, fmt.Errorf("open unit of work: %w", err)
	}
	return uw, nil
}

// runListProxiedTree serves the ONE mode that is deliberately off the role: the
// hierarchical --parent walk under pretty output. It consumes the FILTER as a
// value, re-parenting a copy of it at every level, and it reaches no page
// epilogue on either route.
func runListProxiedTree(ctx context.Context, in listInput) error {
	uw, filter, err := openAndPrepare(ctx, in)
	if err != nil {
		return err
	}
	defer uw.Close(ctx)

	if in.Offset > 0 {
		return fmt.Errorf("--offset is not supported with hierarchical --parent + pretty/tree")
	}
	return runListProxiedHierarchicalParent(ctx, uw, in, filter)
}

// runListProxiedPage is the proxied twin of the direct route's two flips, and
// it is the same two in the same order: --json first, then every text
// rendering, both over issueops.Reader.
//
// It opens no unit of work of its own — the role opens one per call, which is
// one more than this route used to for a listing that also loads dependency
// records. Nothing here was atomic across those reads before either: the
// renderings ran after the query returned.
func runListProxiedPage(ctx context.Context, out io.Writer, in listInput) error {
	rd, err := proxiedIssueReader()
	if err != nil {
		return err
	}

View on GitHub (pinned to 71377f2769)

Solutions

Drop --offset when using --parent with pretty/tree output
Use --limit to cap the tree size instead of paginating
Switch to --json output if you need offset pagination with --parent
Fetch the full tree once and paginate client-side

Example fix

// before
bd list --parent bd-1 --offset 10
// after
bd list --parent bd-1 --limit 100   # or add --json to keep --offset

Defensive patterns

Strategy: validation

Validate before calling

# Refuse --offset with hierarchical parent + pretty output before running
if [[ "$cmd" == *"--parent"* && "$cmd" == *"--offset"* && "$cmd" != *"--json"* ]]; then
  echo "--offset unsupported with --parent pretty output"; exit 2
fi
bd list $cmd

Try / catch

// Detect the combination error and fall back to --json or no offset
out=$(bd list --parent "$id" --offset "$o" 2>&1) || case "$out" in
  *"--offset is not supported"*) bd list --parent "$id";; *) echo "$out";; esac

Prevention

Never paginate tree views with --offset; use --limit
Add --json when you need offset pagination with --parent
Keep pagination scripts mode-aware (pretty vs json)

When it happens

Trigger: `bd list --parent <id> --offset 10` in proxied-server mode with pretty (non-JSON) output. Offset 0 (the default) is allowed.

Common situations: Scripted pagination loops that always pass --offset, combining pagination flags with the tree view, or reusing a generic list invocation template across modes.

Related errors

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