What causes "The definition of "%s" in "%s" must be an array." in symfony/routing?

Make the definition a map: home: { path: '/', controller: ... }.

symfony/routing · error · InvalidArgumentException

The definition of " " in " " must be an array.

Error message

The definition of "%s" in "%s" must be an array.

What it means

The validate() method requires each named routing definition to be an array (a map of config keys). If the parsed value for a route name is a scalar, null, or anything non-array, an InvalidArgumentException is thrown because none of the route/import config can be read from it.

Solutions

Make the definition a map: home: { path: '/', controller: ... }.
Fix YAML indentation so route options are nested under the route name.
Check programmatic config builders for accidental scalar assignment.

Example fix

// before
'home' => '/',
// after
'home' => ['path' => '/'],

Defensive patterns

Strategy: validation

Validate before calling

foreach ($defs as $name => $def) { if (!\is_array($def)) { throw new \InvalidArgumentException("Definition '{$name}' must be an array"); } }

Type guard

function isRouteDefinition(mixed $def): bool { return \is_array($def); }

Try / catch

try { $loader->load($file); } catch (\InvalidArgumentException $e) { /* fix the scalar definition named in the message */ }

Prevention

Every route name must map to a nested map of options.
Validate YAML indentation with a schema linter.
Never assign plain strings to route names in config builders.

When it happens

Trigger: A YAML entry like `home: /` (scalar) instead of `home: { path: / }`; a PHP config array where the route name maps to a string or boolean; mis-indented YAML collapsing a definition into a scalar.

Common situations: YAML indentation mistakes making a definition a plain string; config assembled programmatically with wrong nesting; empty values assigned to route names.

Related errors

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

Appendix: source

Thrown at Loader/ContentLoaderTrait.php:209

            if (null !== $namePrefix) {
                $subCollection->addNamePrefix($namePrefix);
            }
            $subCollection->addDefaults($defaults);
            $subCollection->addRequirements($requirements);
            $subCollection->addOptions($options);

            $collection->addCollection($subCollection);
        }
    }

    /**
     * @throws \InvalidArgumentException If one of the provided config keys is not supported,
     *                                   something is missing or the combination is nonsense
     */
    private function validate(mixed $config, string $name, string $path): void
    {
        if (!\is_array($config)) {
            throw new \InvalidArgumentException(\sprintf('The definition of "%s" in "%s" must be an array.', $name, $path));
        }
        if (isset($config['alias'])) {
            $this->validateAlias($config, $name, $path);

            return;
        }
        if ($extraKeys = array_diff(array_keys($config), self::AVAILABLE_KEYS)) {
            throw new \InvalidArgumentException(\sprintf('The routing file "%s" contains unsupported keys for "%s": "%s". Expected one of: "%s".', $path, $name, implode('", "', $extraKeys), implode('", "', self::AVAILABLE_KEYS)));
        }
        if (isset($config['resource']) && isset($config['path'])) {
            throw new \InvalidArgumentException(\sprintf('The routing file "%s" must not specify both the "resource" key and the "path" key for "%s". Choose between an import and a route definition.', $path, $name));
        }
        if (!isset($config['resource']) && isset($config['type'])) {
            throw new \InvalidArgumentException(\sprintf('The "type" key for the route definition "%s" in "%s" is unsupported. It is only available for imports in combination with the "resource" key.', $name, $path));
        }
        if (!isset($config['resource']) && !isset($config['path'])) {
            throw new \InvalidArgumentException(\sprintf('You must define a "path" for the route "%s" in file "%s".', $name, $path));
        }

View on GitHub (pinned to 83fa223250)