symfony/translation · error · LogicException

Loading translations from the YAML format requires the…

Error message

Loading translations from the YAML format requires the Symfony Yaml component.

What it means

YamlFileLoader relies on symfony/yaml's YamlParser to read translation files. If the Yaml component is not installed, loadResource() throws this LogicException — an optional-dependency guard analogous to the XLIFF loader's Config check.

Solutions

Run composer require symfony/yaml to install the component.
Alternatively switch to a format without the dependency (e.g. PHP array translation files).
Confirm vendor/symfony/yaml exists and the autoload includes it.

Example fix

// before
$loader->load('translations/messages.en.yaml', 'en'); // LogicException
// after
// composer require symfony/yaml
$loader->load('translations/messages.en.yaml', 'en');

Defensive patterns

Strategy: try-catch

Validate before calling

if (!class_exists(\Symfony\Component\Translation\Loader\YamlFileLoader::class) && !class_exists(\Symfony\Component\Yaml\Parser::class)) {
    throw new \LogicException('Install symfony/yaml before loading YAML translations.');
}

Type guard

function canLoadYaml(): bool { return class_exists(\Symfony\Component\Yaml\Parser::class); }

Try / catch

try {
    $catalogue = $loader->load($resource, $locale);
} catch (\LogicException $e) {
    if (str_contains($e->getMessage(), 'requires the Symfony Yaml component')) {
        // composer require symfony/yaml or switch loader format
    }
    throw $e;
}

Prevention

Require symfony/yaml in composer.json when using YAML translations.
Mirror production dependencies in CI (composer install --no-dev still needs it).
Or standardize on PHP array translation files to avoid the dependency.

When it happens

Trigger: Loading a .yaml/.yml translation file (via load() or a Translator using the YAML loader) while class_exists(YamlParser::class) fails because symfony/yaml is not installed.

Common situations: Projects installing only symfony/translation without symfony/yaml; production builds that prune dev/suggested dependencies; framework editions dropping Yaml by default.

Understand the failure class

Background: "not installed", "pip install", "required for": how missing-dependency errors surface across open-source libraries — this error's family across 34 libraries.

Related errors

AI-assisted analysis of symfony/translation@ae9e8a51bc (2026-09-15). Data as JSON: /api/errors/b4f162710e65dbd8. Report an issue: GitHub.

Appendix: source

Thrown at Loader/YamlFileLoader.php:33

use Symfony\Component\Translation\Exception\LogicException;
use Symfony\Component\Yaml\Exception\ParseException;
use Symfony\Component\Yaml\Parser as YamlParser;
use Symfony\Component\Yaml\Yaml;

/**
 * YamlFileLoader loads translations from Yaml files.
 *
 * @author Fabien Potencier <fabien@symfony.com>
 */
class YamlFileLoader extends FileLoader
{
    private YamlParser $yamlParser;

    protected function loadResource(string $resource): array
    {
        if (!isset($this->yamlParser)) {
            if (!class_exists(YamlParser::class)) {
                throw new LogicException('Loading translations from the YAML format requires the Symfony Yaml component.');
            }

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

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

        if (null !== $messages && !\is_array($messages)) {
            throw new InvalidResourceException(\sprintf('Unable to load file "%s".', $resource));
        }

        return $messages ?: [];
    }
}

View on GitHub (pinned to ae9e8a51bc)