{"record":{"id":"90f3bcaf05ac389d","repo":"symfony/routing","slug":"the-file-s-must-contain-a-yaml-array","errorCode":null,"errorMessage":"The file \"%s\" must contain a YAML array.","messagePattern":"The file \"(.+?)\" must contain a YAML array\\.","errorType":"exception","errorClass":"InvalidArgumentException","httpStatus":null,"severity":"error","filePath":"Loader/YamlFileLoader.php","lineNumber":70,"sourceCode":"        $this->yamlParser ??= new YamlParser();\n\n        try {\n            $parsedConfig = $this->yamlParser->parseFile($path, Yaml::PARSE_CONSTANT);\n        } catch (ParseException $e) {\n            throw new \\InvalidArgumentException(\\sprintf('The file \"%s\" does not contain valid YAML: ', $path).$e->getMessage(), 0, $e);\n        }\n\n        $collection = new RouteCollection();\n        $collection->addResource(new FileResource($path));\n\n        // empty file\n        if (null === $parsedConfig) {\n            return $collection;\n        }\n\n        // not an array\n        if (!\\is_array($parsedConfig)) {\n            throw new \\InvalidArgumentException(\\sprintf('The file \"%s\" must contain a YAML array.', $path));\n        }\n\n        $this->loadContent($collection, $parsedConfig, $path, $file);\n\n        return $collection;\n    }\n\n    public function supports(mixed $resource, ?string $type = null): bool\n    {\n        return \\is_string($resource) && \\in_array(pathinfo($resource, \\PATHINFO_EXTENSION), ['yml', 'yaml'], true) && (!$type || 'yaml' === $type);\n    }\n\n    /**\n     * Parses a route and adds it to the RouteCollection.\n     */\n    protected function parseRoute(RouteCollection $collection, string $name, array $config, string $path): void\n    {\n        $this->doParseRoute($collection, $name, $config, $path);","sourceCodeStart":52,"sourceCodeEnd":88,"githubUrl":"https://github.com/symfony/routing/blob/83fa223250b50f4f018c011e101c330e65ac63cc/Loader/YamlFileLoader.php#L52-L88","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Ensure the top level is a mapping: each route name as a key with path/controller sub-keys","If the file should be empty, make it truly empty or comment-only (null parses to an empty collection)","Validate the parsed root type before loading"],"exampleFix":"// routes.yaml before (top-level list)\n- path: /\n  controller: App\\Controller\\HomeController::index\n// after\nindex:\n    path: /\n    controller: App\\Controller\\HomeController::index","handlingStrategy":"validation","validationCode":"$parsed = (new \\Symfony\\Component\\Yaml\\Parser())->parseFile($path); if ($parsed !== null && !is_array($parsed)) { throw new \\RuntimeException('Routing YAML root must be a mapping'); }","typeGuard":"null","tryCatchPattern":"try { $loader->load($file); } catch (\\InvalidArgumentException $e) { if (str_contains($e->getMessage(), 'YAML array')) { /* fix root structure */ } throw $e; }","preventionTips":["Always write routing files as a mapping of route-name keys","Test that every routes*.yaml loads during CI","Avoid templating outputs that emit a scalar or sequence at the root"],"tags":["routing","yaml","config","symfony"],"backgroundTag":"schema-validation-failed","analyzedSha":"83fa223250b50f4f018c011e101c330e65ac63cc","analyzedAt":"2026-09-14T03:19:46.280Z","contentChangedAt":"2026-09-14T03:19:46.280Z","schemaVersion":2},"datasetVersion":"2026-09-16T09:17:16.951Z"}