cakephp/cakephp · error · CakeException

You must set a pagination instance using `setPaginated()`…

Error message

You must set a pagination instance using `setPaginated()` first

What it means

PaginatorHelper methods that read pagination metadata (params, current, total, links, prev/next checks) require a PaginatedInterface instance to have been injected via setPaginated(). If none was set, the helper's `paginated()` accessor throws a generic CakeException instead of silently returning null.

Solutions

1. Ensure the controller action calls `$this->paginate($query)` so the Paginated result is set on the request and helper
2. Call `$this->Paginator->setPaginated($paginatedResult)` explicitly before using any helper methods
3. Guard template usage with `$this->Paginator->hasPaginated()` (or an isset check) before rendering pagination controls
4. If pagination is optional in a shared element, render controls only when pagination data exists

Example fix

// before
<?= $this->Paginator->total() ?>
// after
<?php if ($this->Paginator->hasPaginated()): ?>
  <?= $this->Paginator->total() ?>
<?php endif; ?>

if (method_exists($this->Paginator, 'hasPaginated') ? $this->Paginator->hasPaginated() : false) { /* render pagination */ }

try {
    $total = $this->Paginator->total();
} catch (CakeException $e) {
    $total = 0; // view rendered without pagination
}

When it happens

Trigger: Calling `$this->Paginator->params()`, `current()`, `total()`, `hasPrev()`, `hasNext()` or `_toggledLink()` in a template/view when setPaginated() was never called — typically because the view was rendered outside a paginated controller action, or the helper was used manually.

Common situations: Using PaginatorHelper in a non-paginated template (e.g. an element rendered on a page without a `paginate()` call); using the helper in a console/standalone View; upgrading from CakePHP 3 where request-based paging params were read implicitly.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Cannot use both `steps` option and explicit `$limits`…
• Missing required route key
• Need a valid Closure to connect routes.

AI-assisted analysis of cakephp/cakephp@1128eba9b0 (2026-09-12). Data as JSON: /api/errors/10a96d909940f2c1. Report an issue: GitHub.

Appendix: source

Thrown at src/View/Helper/PaginatorHelper.php:156

    /**
     * Get pagination instance.
     *
     * @return \Cake\Datasource\Paging\PaginatedInterface<array-key, mixed>
     */
    protected function paginated(): PaginatedInterface
    {
        if (!isset($this->paginated)) {
            foreach ($this->_View->getVars() as $name) {
                $value = $this->_View->get($name);
                if ($value instanceof PaginatedInterface) {
                    $this->paginated = $value;
                }
            }
        }

        if (!isset($this->paginated)) {
            throw new CakeException('You must set a pagination instance using `setPaginated()` first');
        }

        return $this->paginated;
    }

    /**
     * Gets the current paging parameters from the result set for the given model
     *
     * @return array The array of paging parameters for the paginated result set.
     */
    public function params(): array
    {
        return $this->getConfig('params') + $this->paginated()->pagingParams();
    }

    /**
     * Convenience access to any of the paginator params.
     *

View on GitHub (pinned to 1128eba9b0)