gohugoio/hugo · error

'paginate' configuration setting must be positive to paginat

Error message

'paginate' configuration setting must be positive to paginate

What it means

Raised at the top of page.Paginate when the resolved pager size is <= 0. The size comes from the `pagination.pagerSize` (formerly `paginate`) site config or the explicit argument; a zero or negative value makes pagination meaningless, so Hugo refuses to build.

Source

Thrown at resources/page/pagination.go:284

		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
	}
	if ok {
		paginator, _ = newPaginatorFromPageGroups(groups, pagerSize, urlFactory)
	} else {
		pages, err := ToPages(seq)
		if err != nil {
			return nil, err
		}
		paginator, _ = newPaginatorFromPages(pages, pagerSize, urlFactory)

View on GitHub ↗ (pinned to 8a468df065)

Solutions

1. Set a positive pager size in config, e.g. `[pagination]\npagerSize = 10` in hugo.toml
2. To effectively show everything on one page, use a large pager size or drop .Paginate and range .Pages directly
3. Check per-environment config files for an override zeroing the value

Example fix

# before (hugo.toml)
[pagination]
pagerSize = 0
# after
[pagination]
pagerSize = 10

# hugo.toml
[pagination]
pagerSize = 10  # must be > 0

When it happens

Trigger: Using .Paginate/.Paginator in a template while site config sets `pagination.pagerSize = 0` (or a negative number), or explicitly disabling pagination via config while a list template still calls .Paginate.

Common situations: Setting `paginate = 0` hoping to "show all pages" (unsupported — the setting must stay positive), config-migration mistakes from the old `paginate` key to `pagination.pagerSize`, or environment-specific config overriding the value to 0.

Related errors

• failed to detect target data serialization format
• unsupported transpiler %q; valid values are %q or %q
• cannot convert type %T to Pages
• unsupported type in paginate from slice, got %T instead of P
• too many arguments, 'pager size' is currently the only optio

AI-assisted analysis of gohugoio/hugo@8a468df065 (2026-07-31). Data as JSON: /data/errors/43fe3f836712d6e7.json. Report an issue: GitHub ↗.