flarum/framework · error · BadRequestException

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

Error message

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

What it means

DialogMessageResource restricts the page[near] pagination parameter: it may only be combined with a single filter[dialog] and the default sort (number desc). Anything else throws a BadRequestException in the endpoints() hook.

Solutions

  1. Add filter[dialog]=<dialogId> to the request.
  2. Remove all other filters so only filter[dialog] remains.
  3. Drop any sort parameter or use the default sort (number desc).
  4. If you need other filter/sort combinations, fetch without page[near] and paginate normally.

Example fix

// before
GET /api/dialog-messages?page[near]=5&sort=-id
// after
GET /api/dialog-messages?filter[dialog]=12&page[near]=5
Defensive patterns

Strategy: validation

Validate before calling

const ok = 'near' in page && Object.keys(filter).length === 1 && 'dialog' in filter && (!sort || JSON.stringify(sort) === JSON.stringify({number:'desc'})); if (!ok) throw new Error('page[near] requires only filter[dialog] and default sort');

Try / catch

try { const res = await api.get('/api/dialog-messages', params); } catch (e) { if (e.status === 400 && /page\[near\]/.test(e.message)) { /* fix query params */ } }

Prevention

When it happens

Trigger: Requesting /api/dialog-messages with page[near] while either filtering by more than just dialog, omitting filter[dialog], or passing a non-default sort (e.g. sort by id or number asc).

Common situations: Frontend passing extra filters (e.g. user filter) together with near-pagination; sorting params leaking from a generic list view; calling the API without scoping to one dialog.

Understand the failure class

Background: "Invalid query parameter" / "Failed to parse value of ...": fixing bad query string parameters across APIs — this error's family across 36 libraries.

Related errors

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

Appendix: source

Thrown at extensions/messages/src/Api/Resource/DialogMessageResource.php:123

                ->defaultSort('-number')
                ->eagerLoad(function () {
                    if ($this->extensions->isEnabled('flarum-mentions')) {
                        return ['mentionsUsers', 'mentionsPosts', 'mentionsGroups', 'mentionsTags'];
                    }

                    return [];
                })
                ->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'];
                        $dialogId = $filter['dialog'] ?? null;

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

                        $limit = $defaultExtracts['limit'];

                        $index = DialogMessage::query()
                            ->where('dialog_id', $dialogId)
                            ->where('number', '>=', $near)
                            ->orderBy('number', 'desc')
                            ->whereVisibleTo($context->getActor())
                            ->count();

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

                    return $defaultExtracts['offset'];
                })

View on GitHub (pinned to 4b939f6853)