symfony/routing · error · InvalidArgumentException

The Router does not support the

Error message

The Router does not support the "%s" option.

What it means

Symfony's Router only supports a fixed set of options (cache_dir, debug, generator_class, generator_dumper_class, matcher_class, matcher_dumper_class, resource_type, strict_requirements). Router::setOption() checks the key against $this->options (initialized in setOptions()) and throws InvalidArgumentException for any unknown key, failing fast on typos or removed options.

Solutions

1. Check the key against the supported list in Router::setOptions() docblock (Router.php:70-81): cache_dir, debug, generator_class, generator_dumper_class, matcher_class, matcher_dumper_class, resource_type, strict_requirements.
2. Fix typos and casing — keys are case-sensitive snake_case (e.g. 'cacheDir' → 'cache_dir').
3. If the option came from an older Symfony version, look up its current replacement in the docs (e.g. matcher_class customization moved to services in newer versions) and pass it where the new version expects it.
4. If passing many options, use the constructor $options array or setOptions() instead, which reports all invalid keys at once.
5. Wrap in a check before calling: array via getOption on a known key or compare against a whitelist constant.

Example fix

// before
$router->setOption('cacheDir', '/var/cache/router');
// InvalidArgumentException: The Router does not support the "cacheDir" option.

// after
$router->setOption('cache_dir', '/var/cache/router');

const ROUTER_OPTIONS = ['cache_dir','debug','generator_class','generator_dumper_class','matcher_class','matcher_dumper_class','resource_type','strict_requirements'];
if (!in_array($key, ROUTER_OPTIONS, true)) {
    throw new LogicException(sprintf('Unknown Router option "%s"; supported: %s', $key, implode(', ', ROUTER_OPTIONS)));
}
$router->setOption($key, $value);

function isValidRouterOption(string $key): bool
{
    return in_array($key, ['cache_dir','debug','generator_class','generator_dumper_class','matcher_class','matcher_dumper_class','resource_type','strict_requirements'], true);
}

try {
    $router->setOption($key, $value);
} catch (\InvalidArgumentException $e) {
    $this->logger->error('Invalid router option', ['key' => $key, 'message' => $e->getMessage()]);
    throw new \LogicException($e->getMessage(), 0, $e);
}

When it happens

Trigger: Calling $router->setOption('some_key', $value) with a key that is not one of the 8 supported option names, e.g. a typo like 'cache_dir ' (trailing space), 'cachedir', 'cacheDir' (wrong case), or an option from a different component.

Common situations: Typo or wrong casing in an option name; copying options from an older/newer Symfony version where an option was renamed or removed; passing framework-bundle config keys (e.g. 'utf8', 'matcher.cache_dir' from YAML config) directly to the Router class.

Related errors

• The Router does not support the following options
• Cannot use UTF-8 route patterns without setting the "utf8"…
• Parameter " " for route " " must match " " (" " given) to…
• Parameters for route
• Route aliases cannot be used on non-invokable class

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

Appendix: source

Thrown at Router.php:120

            } else {
                $invalid[] = $key;
            }
        }

        if ($invalid) {
            throw new \InvalidArgumentException(\sprintf('The Router does not support the following options: "%s".', implode('", "', $invalid)));
        }
    }

    /**
     * Sets an option.
     *
     * @throws \InvalidArgumentException
     */
    public function setOption(string $key, mixed $value): void
    {
        if (!\array_key_exists($key, $this->options)) {
            throw new \InvalidArgumentException(\sprintf('The Router does not support the "%s" option.', $key));
        }

        $this->options[$key] = $value;
    }

    /**
     * Gets an option value.
     *
     * @throws \InvalidArgumentException
     */
    public function getOption(string $key): mixed
    {
        if (!\array_key_exists($key, $this->options)) {
            throw new \InvalidArgumentException(\sprintf('The Router does not support the "%s" option.', $key));
        }

        return $this->options[$key];
    }

View on GitHub (pinned to 83fa223250)