flarum/framework · error · BadRequestException

You can only use page[near] with filter[discussion] and the…

Error message

You can only use page[near] with filter[discussion] and the default sort order

What it means

Validation error raised in PostResource's Index endpoint offset extraction: page[near] (jump-to-post-number) is only meaningful when scoping posts to a single discussion via filter[discussion] and using the default sort order; any other combination would produce ambiguous or wrong offsets, so the request is rejected.

Solutions

1. Add filter[discussion]=<discussion id> to the query when using page[near]
2. Remove page[near] and use plain page[number]/page[size] pagination when listing all posts
3. Drop any custom sort parameter so the default sort order is used with page[near]

When it happens

Trigger: Thrown at framework/core/src/Api/Resource/PostResource.php:134 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of flarum/framework@4b939f6853 (2026-09-15). Data as JSON: /api/errors/dea07aa6dca3c4e9. Report an issue: GitHub.

Appendix: source

Thrown at framework/core/src/Api/Resource/PostResource.php:134

                ->defaultInclude([
                    'user',
                    'user.groups',
                    'editedUser',
                    'hiddenUser',
                    'discussion'
                ])
                ->eagerLoad(['user.groups', 'discussion.state']),
            Endpoint\Index::make()
                ->extractOffset(function (Context $context, array $defaultExtracts): int {
                    $queryParams = $context->request->getQueryParams();
                    $near = intval(Arr::get($queryParams, 'page.near'));

                    if ($near > 1) {
                        $sort = $defaultExtracts['sort'];
                        $filter = $defaultExtracts['filter'];

                        if (count($filter) > 1 || ! isset($filter['discussion']) || ($sort && $sort !== ['number' => 'asc'])) {
                            throw new BadRequestException(
                                'You can only use page[near] with filter[discussion] and the default sort order'
                            );
                        }

                        $limit = $defaultExtracts['limit'];
                        $index = $this->posts->getIndexForNumber((int) $filter['discussion'], $near, $context->getActor());

                        return max(0, $index - $limit / 2);
                    }

                    return $defaultExtracts['offset'];
                })
                ->defaultInclude([
                    'user',
                    'user.groups',
                    'editedUser',
                    'hiddenUser',
                    'discussion'

View on GitHub (pinned to 4b939f6853)