adaptive height is not compatible with top/bottom percent ma

Error message

adaptive height is not compatible with top/bottom percent margin

What it means

When height is adaptive (--height ~N%), fzf cannot also compute top/bottom margins as a percentage of the screen, because both derive from the total screen height and would be circular. The check at options.go:3647 fires when opts.Height.auto is set (and not overridden by a later tmux height option) and either the top (Margin[0]) or bottom (Margin[2]) sizeSpec is a percent value.

Source

Thrown at src/options.go:3647

		return errors.New("gutter display width should be 1")
	}

	if opts.Scrollbar != nil {
		runes := []rune(*opts.Scrollbar)
		if len(runes) > 2 {
			return errors.New("--scrollbar should be given one or two characters")
		}
		for _, r := range runes {
			if uniseg.StringWidth(string(r)) != 1 {
				return errors.New("scrollbar display width should be 1")
			}
		}
	}

	if opts.Height.auto && (opts.Tmux == nil || opts.Tmux.index < opts.Height.index) {
		for _, s := range []sizeSpec{opts.Margin[0], opts.Margin[2]} {
			if s.percent {
				return errors.New("adaptive height is not compatible with top/bottom percent margin")
			}
		}
		for _, s := range []sizeSpec{opts.Padding[0], opts.Padding[2]} {
			if s.percent {
				return errors.New("adaptive height is not compatible with top/bottom percent padding")
			}
		}
	}

	if opts.Theme.Nth.IsColorDefined() {
		return errors.New("only ANSI attributes are allowed for 'nth' (regular, bold, underline, reverse, dim, italic, strikethrough)")
	}

	if opts.BorderShape == tui.BorderInline ||
		opts.ListBorderShape == tui.BorderInline ||
		opts.InputBorderShape == tui.BorderInline ||
		opts.Preview.border == tui.BorderInline {
		return errors.New("inline border is only supported for --header-border, --header-lines-border, and --footer-border")

View on GitHub (pinned to bd4efa277b)

Solutions

Use fixed (absolute) values for top/bottom margins with adaptive height (e.g. -m 2,4,2,4)
Or switch to a fixed height so percent margins are computable
In wrappers, detect --height values starting with '~' and downgrade percent margins to numbers

Example fix

# before
fzf --height=~50% --margin=10%,0,10%,0
# after
fzf --height=~50% --margin=4,0,4,0

Defensive patterns

Strategy: validation

Validate before calling

// Shell: downgrade percent margins when height is adaptive
case "$height" in '~'*) margins='4,2,4,2' ;; esac   # absolute top/bottom
exec fzf --height="$height" --margin="$margins"

Prevention

Never combine --height=~… with percent top/bottom margins
When height is adaptive, use absolute margin numbers
Centralize layout options so height/margin rules are checked in one place

When it happens

Trigger: Combining --height='~50%' with -m 10%,10% or --margin='10%,5%,10%,5%'. Adaptive height plus any percent top/bottom margin triggers the error.

Common situations: Copy-pasted margin settings from a fixed-height layout into an adaptive-height one; migrating scripts to --height=~100% while keeping percent margins; wrapper scripts composing both options from user config.

Related errors

AI-assisted analysis of junegunn/fzf@bd4efa277b (2026-08-15). Data as JSON: /api/errors/c5a74a29f60ab6f0. Report an issue: GitHub.