symfony/routing · error · InvalidArgumentException

The file " " must contain a YAML array.

Error message

The file "%s" must contain a YAML array.

What it means

YamlFileLoader::load() accepts only an array (mapping) at the top level of the routing YAML file; an empty file yields null and returns an empty collection, but a scalar/string top level is invalid. Symfony throws this InvalidArgumentException when parseFile returns a non-array, non-null value.

Solutions

1. Ensure the top level is a mapping: each route name as a key with path/controller sub-keys
2. If the file should be empty, make it truly empty or comment-only (null parses to an empty collection)
3. Validate the parsed root type before loading

Example fix

// routes.yaml before (top-level list)
- path: /
  controller: App\Controller\HomeController::index
// after
index:
    path: /
    controller: App\Controller\HomeController::index

$parsed = (new \Symfony\Component\Yaml\Parser())->parseFile($path); if ($parsed !== null && !is_array($parsed)) { throw new \RuntimeException('Routing YAML root must be a mapping'); }

null

try { $loader->load($file); } catch (\InvalidArgumentException $e) { if (str_contains($e->getMessage(), 'YAML array')) { /* fix root structure */ } throw $e; }

When it happens

Trigger: routes.yaml containing a top-level scalar like just "my route" or a YAML list at the root (a sequence of dash lines) instead of a mapping of route names; a file that unescaped characters collapsed into a scalar.

Common situations: Beginners writing routes as a YAML sequence; template-generated files that render a bare string; splitting route definitions with a top-level key in an imported file where the root mapping was expected.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Namespace " " is not a valid PSR-4 prefix.
• This is not a local file
• File " " not found.
• The file " " does not contain valid YAML
• Parameter " " for route " " must match " " (" " given) to…

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

Appendix: source

Thrown at Loader/YamlFileLoader.php:70

        $this->yamlParser ??= new YamlParser();

        try {
            $parsedConfig = $this->yamlParser->parseFile($path, Yaml::PARSE_CONSTANT);
        } catch (ParseException $e) {
            throw new \InvalidArgumentException(\sprintf('The file "%s" does not contain valid YAML: ', $path).$e->getMessage(), 0, $e);
        }

        $collection = new RouteCollection();
        $collection->addResource(new FileResource($path));

        // empty file
        if (null === $parsedConfig) {
            return $collection;
        }

        // not an array
        if (!\is_array($parsedConfig)) {
            throw new \InvalidArgumentException(\sprintf('The file "%s" must contain a YAML array.', $path));
        }

        $this->loadContent($collection, $parsedConfig, $path, $file);

        return $collection;
    }

    public function supports(mixed $resource, ?string $type = null): bool
    {
        return \is_string($resource) && \in_array(pathinfo($resource, \PATHINFO_EXTENSION), ['yml', 'yaml'], true) && (!$type || 'yaml' === $type);
    }

    /**
     * Parses a route and adds it to the RouteCollection.
     */
    protected function parseRoute(RouteCollection $collection, string $name, array $config, string $path): void
    {
        $this->doParseRoute($collection, $name, $config, $path);

View on GitHub (pinned to 83fa223250)