gohugoio/hugo · error

'paginate' configuration setting must be positive to…

Error message

'paginate' configuration setting must be positive to paginate

What it means

`Paginate` (pagination.go:282-285) requires a positive pager size to split pages into pages. When the resolved size is <= 0 (often from a missing/zero `paginate` config setting), pagination cannot proceed and the call errors.

Solutions

1. Set `paginate` to a positive integer in hugo.toml, e.g. `paginate = 10`.
2. Remove the `.Paginator`/`.Paginate` call from templates if pagination is intentionally disabled.
3. If using `.Paginate $pages N`, pass an explicit positive N to override the config.

Example fix

# before
paginate = 0

# after
paginate = 10

if pagerSize <= 0 { return errors.New("'paginate' configuration setting must be positive to paginate") }

When it happens

Trigger: Building with `paginate = 0` (or negative) in hugo.toml, or omitting `paginate` in a setup where it resolves to 0, then calling `.Paginator`/`.Paginate` in a template.

Common situations: Disabling pagination by setting `paginate = 0` but still calling `.Paginator`; fresh config without a `paginate` key resolving to 0; inheriting a theme that paginates while the project disabled it.

Related errors

• 'pager size' must be a positive integer
• too many arguments, 'pager size' is currently the only…
• can't apply the operator to the values
• cannot use --renderToMemory with --destination
• cardinalityThreshold threshold must be between 0 and 100

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

Appendix: 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 52c9bd7908)