gohugoio/hugo · error

'pager size' must be a positive integer

Error message

'pager size' must be a positive integer

What it means

When exactly one option is given to `ResolvePagerSize`, it is cast to an int and must be positive (pagination.go:273-277). Zero, negative, or non-integer values are rejected because they would produce an empty or invalid paginator.

Source

Thrown at resources/page/pagination.go:276

		split = append(split, pg)
	}

	return split
}

func ResolvePagerSize(conf config.AllProvider, options ...any) (int, error) {
	if len(options) == 0 {
		return conf.Pagination().PagerSize, nil
	}

	if len(options) > 1 {
		return -1, errors.New("too many arguments, 'pager size' is currently the only option")
	}

	pas, err := cast.ToIntE(options[0])

	if err != nil || pas <= 0 {
		return -1, errors.New(("'pager size' must be a positive integer"))
	}

	return pas, nil
}

func Paginate(td TargetPathDescriptor, seq any, pagerSize int) (*Paginator, error) {
	if pagerSize <= 0 {
		return nil, errors.New("'paginate' configuration setting must be positive to paginate")
	}

	urlFactory := newPaginationURLFactory(td)

	var paginator *Paginator

	groups, ok, err := ToPagesGroup(seq)
	if err != nil {
		return nil, err
	}

View on GitHub (pinned to 52c9bd7908)

Solutions

1. Pass a positive integer literal or variable, e.g. `{{ .Paginate $pages 12 }}`.
2. If you want the configured default, omit the option entirely.
3. Ensure any computed size is clamped to >= 1.

Example fix

{{/* before */}}
{{ .Paginate $pages 0 }}

{{/* after */}}
{{ .Paginate $pages 12 }}

n, err := cast.ToIntE(opt)
if err != nil || n <= 0 { return errors.New("'pager size' must be a positive integer") }

When it happens

Trigger: Calling `{{ .Paginate $pages 0 }}`, `{{ .Paginate $pages -1 }}`, or `{{ .Paginate $pages "ten" }}` — the option fails to cast to a positive int.

Common situations: Passing a string instead of a number; passing 0 thinking it means "default"; arithmetic that underflows to zero or negative; typo in a computed pager size.

Related errors

• too many arguments, 'pager size' is currently the only optio
• quality ranges from 1 to 100 inclusive
• invalid image dimensions
• must provide Width and Height
• must provide Width or Height

AI-assisted analysis of gohugoio/hugo@52c9bd7908 (2026-08-09). Data as JSON: /api/errors/c8466d706de82db1. Report an issue: GitHub.