flarum/framework · error · BadRequestException

Invalid fields [

Error message

Invalid fields [

What it means

When an $available whitelist is passed to RequestUtil::extractFields(), any field key in the 'fields' query param not present in the whitelist triggers BadRequestException listing the invalid keys. This guards against clients requesting sparse fieldsets for relationship types the endpoint does not expose.

Solutions

1. Change the query to use only whitelisted keys shown in the error message
2. Fix the typo or update the client to the current relationship name
3. On the server, extend the $available array if the field is legitimately supported
4. Catch BadRequestException and return it to the client with the list of allowed fields

Example fix

// before
GET /api/posts?fields[usr]=title
// after
GET /api/posts?fields[posts]=title

$requested = array_keys((array) ($request->getQueryParams()['fields'] ?? []));
$allowed = ['posts', 'users'];
if (count(array_diff($requested, $allowed))) { /* reject before calling */ }

try {
    $fields = RequestUtil::extractFields($request, ['posts', 'users']);
} catch (BadRequestException $e) {
    return response()->json(['error' => $e->getMessage(), 'allowed' => ['posts','users']], 400);
}

When it happens

Trigger: GET with e.g. ?fields[user]=name on an endpoint that only allows $available=['posts']; any typo in the fields sub-key; requesting fields for a relationship removed in a newer API version.

Common situations: Client-server API version skew after renames; typos in relationship names; copy-pasted query strings between endpoints with different whitelists.

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

• fields must be an array
• flarum-akismet.admin.akismet_settings.invalid_api_key_messag…
• Incorrect password
• Invalid erasure mode: $mode
• You can only use page[near] with filter[dialog] and the…

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

Appendix: source

Thrown at framework/core/src/Http/RequestUtil.php:245

            throw new BadRequestException('filter must be an array');
        }

        return $filter;
    }

    public static function extractFields(Request $request, ?array $available = null): array
    {
        $fields = $request->getQueryParams()['fields'] ?? [];

        if (! is_array($fields)) {
            throw new BadRequestException('fields must be an array');
        }

        if ($available !== null) {
            $invalid = array_diff(array_keys($fields), $available);

            if (count($invalid)) {
                throw new BadRequestException('Invalid fields ['.implode(',', $invalid).']');
            }
        }

        return $fields;
    }
}

View on GitHub (pinned to 4b939f6853)