---
title: "Unknown parameters & errors — Query Builder for Laravel | Roundly"
description: "Un-allow-listed filters and sorts return HTTP 400 with a translatable, length-capped message — or are dropped in ignore mode."
url: https://roundly-consulting.com/open-source/docs/query-builder-for-laravel/unknown-parameters
language: en
---

[All packages](https://roundly-consulting.com/open-source.md)

[Query Builder for Laravel](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel.md)

# Unknown parameters & errors

Requesting a filter or sort that is not allow-listed throws UnknownFilter or UnknownSort. Both extend Symfony’s HttpException with a 400 status, so Laravel renders them as a normal HTTP error:

```
GET /posts?filter[secret]=1

HTTP/1.1 400 Bad Request
{"message": "Requested filter(s) `secret` are not allowed. Allowed filter(s) are `status, title`."}
```

## Ignore mode

Set mode.unknown\_filter or mode.unknown\_sort to ignore to drop the offending key silently and apply only the allow-listed ones. A sort string that is dropped entirely reads as if it were absent, so defaultSort() still orders the page. Any value other than reject or ignore throws InvalidConfigurationException instead of guessing:

```php
// config/query-builder.php
'mode' => [
    'unknown_filter' => 'ignore',   // drop un-allow-listed filters
    'unknown_sort'   => 'reject',   // keep sorts strict (HTTP 400)
],
```

## Messages & translations

Messages come from query-builder::errors.unknown\_filter and query-builder::errors.unknown\_sort, with :unknown and :allowed placeholders. The reflected unknown keys are capped — the first 5, each truncated to 64 characters, with an “…and N more” suffix — so attacker-controlled keys cannot flood the response or your logs. English and Slovak ship, so with the application locale set to sk the message reads in Slovak. Publish the translations to reword them or add a language — the published Slovak file:

```php
// lang/vendor/query-builder/sk/errors.php
return [
    'unknown_filter' => 'Požadované filtre `:unknown` nie sú povolené. Povolené filtre sú `:allowed`.',
    'unknown_sort' => 'Požadované zoradenia `:unknown` nie sú povolené. Povolené zoradenia sú `:allowed`.',
];
```

## Exception reference

| Exception | Thrown when |
| --- | --- |
| `UnknownFilter` | A requested filter key is not allow-listed (reject mode). Symfony HttpException, status 400. |
| `UnknownSort` | A requested sort key is not allow-listed (reject mode). Symfony HttpException, status 400. |
| `UnsupportedOperator` | A filter is declared with an operator it cannot perform. A LogicException — a developer mistake, raised when the filter is built. |
| `InvalidFilterDeclaration` | A filter is declared with arguments it cannot work with — a search() with no columns, a column that is an SQL expression, or an asText column it does not search. A LogicException, raised when the filter is built. |
| `AllowListAlreadyApplied` | allowedFilters(), allowedSorts() or defaultSort() is called after the request was already applied by a forwarded builder call. A LogicException — a developer mistake, never request-triggered. |
| `QueryBuilderException` | Marker interface implemented by all five — catch it to handle the family. |

```php
use RoundlyConsulting\QueryBuilder\Exceptions\QueryBuilderException;

try {
    $posts = QueryBuilder::for(Post::class, $request)
        ->allowedFilters('status')
        ->get();                        // filters apply here — lazily
} catch (QueryBuilderException $e) {
    // UnknownFilter / UnknownSort — both carry HTTP status 400
}
```

## Show your open-source love

This package is free and MIT-licensed. If it saves you time, a one-off donation or a Patreon membership keeps it maintained, tested and documented.

[More ways to support, including crypto](https://roundly-consulting.com/support-us.md)

By donating, you agree to our [donation terms](https://roundly-consulting.com/donation-terms.md).

[Support our open source work (opens in a new tab)](https://donate.stripe.com/dRmeVe8FX5PF1Qd9pXcEw00) [Join us on Patreon (opens in a new tab)](https://www.patreon.com/cw/roundly)

## Want this built into your product?

We integrate our packages into custom Laravel and AI builds. Tell us what you're working on and we'll reply within 48 hours.

[Get a quote in 48 hours](https://roundly-consulting.com/contact.md) [Browse all packages](https://roundly-consulting.com/open-source/docs/query-builder-for-laravel.md)