symfony/routing · error · InvalidParameterException

Parameter "_query" must be an array of query parameters.

Error message

Parameter "_query" must be an array of query parameters.

What it means

When generating a URL, a caller may pass '_query' in the parameters to supply extra query parameters. This error means the passed '_query' value is not an array, so it cannot be used as query parameters.

Solutions

1. Pass an array: ['_query' => ['a' => '1']].
2. Append the query string manually to the generated URL instead of via _query.
3. Remove _query if the parameters are not intended as query overrides.

Example fix

// before
$generator->generate('list', ['_query' => 'page=2']);
// after
$generator->generate('list', ['_query' => ['page' => 2]]);

if (isset($params['_query']) && !is_array($params['_query'])) {
    throw new LogicException('"_query" generate parameter must be an array.');
}

function isValidQueryParam(mixed $v): bool { return !isset($v) || is_array($v); }
// usage: generate($name, array_filter($params, 'isValidQueryParam'))

use Symfony\Component\Routing\Exception\InvalidParameterException;
try { $url = $generator->generate($name, $params); } catch (InvalidParameterException $e) { // non-array _query
    $url = $generator->generate($name, array_diff_key($params, ['_query' => null]));
}

When it happens

Trigger: Calling $generator->generate('route', ['_query' => 'a=1']) or otherwise passing a non-array _query parameter.

Common situations: Passing a query string instead of an array; copying controller defaults syntax into runtime generate() parameters.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Using "%% %%" is not allowed in routing configuration.
• The container parameter
• The container parameter
• Unable to generate a URL for the named route
• Target route " " for alias " " does not exist.

AI-assisted analysis of symfony/routing@83fa223250 (2026-09-14). Data as JSON: /api/errors/be19b8c3cb550d5a. Report an issue: GitHub.

Appendix: source

Thrown at Generator/UrlGenerator.php:159

     * @throws InvalidParameterException           When a parameter value for a placeholder is not correct because
     *                                             it does not match the requirement
     */
    protected function doGenerate(array $variables, array $defaults, array $requirements, array $tokens, array $parameters, string $name, int $referenceType, array $hostTokens, array $requiredSchemes = []): string
    {
        $defaultQuery = $defaults['_query'] ?? [];

        if (!\is_array($defaultQuery)) {
            throw new InvalidParameterException(\sprintf('Default "_query" must be an array of query parameters for route "%s".', $name));
        }

        $queryParameters = [];

        if (isset($parameters['_query'])) {
            if (\is_array($parameters['_query'])) {
                $queryParameters = $parameters['_query'];
                unset($parameters['_query']);
            } else {
                throw new InvalidParameterException('Parameter "_query" must be an array of query parameters.');
            }
        }

        $variables = array_flip($variables);
        $mergedParams = array_replace($defaults, $this->context->getParameters(), $parameters);

        // all params must be given
        if ($diff = array_diff_key($variables, $mergedParams)) {
            throw new MissingMandatoryParametersException($name, array_keys($diff));
        }

        $url = '';
        $optional = true;
        $message = 'Parameter "{parameter}" for route "{route}" must match "{expected}" ("{given}" given) to generate a corresponding URL.';
        foreach ($tokens as $token) {
            if ('variable' === $token[0]) {
                $varName = $token[3];
                // variable is not important by default

View on GitHub (pinned to 83fa223250)