phalcon/cphalcon · error · Phalcon\Config\Exceptions\MissingYamlExtension

Yaml extension is not loaded

Error message

Yaml extension is not loaded

What it means

Config\Adapter\Yaml requires the PECL yaml extension. Before parsing anything, the constructor checks extension_loaded('yaml'); if the extension is not active in the current PHP runtime, MissingYamlExtension is thrown regardless of whether the file is valid.

Source

Thrown at phalcon/Config/Adapter/Yaml.zep:70

 * echo $config->phalcon->controllersDir;
 * echo $config->phalcon->baseuri;
 * echo $config->models->metadata;
 *```
 */
class Yaml extends Config
{
    use InfoTrait;
    use YamlTrait;

    /**
     * Phalcon\Config\Adapter\Yaml constructor
     */
    public function __construct( string filePath,  array callbacks = null)
    {
        var yamlConfig;

        if unlikely !this->phpExtensionLoaded("yaml") {
            throw new MissingYamlExtension();
        }

        if empty(callbacks) {
            let yamlConfig = this->phpYamlParseFile(filePath);
        } else {
            let yamlConfig = this->phpYamlParseFile(filePath, 0, callbacks);
        }

        if unlikely yamlConfig === null {
            let yamlConfig = [];
        }

        if unlikely yamlConfig === false {
            throw new CannotLoadConfigFile(basename(filePath));
        }

        parent::__construct(yamlConfig);
    }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Install and enable the extension: pecl install yaml (or apt install php-yaml), then restart PHP/FPM
2. Or switch to an adapter with no extra dependency (Php, Ini, or Json)
3. Guard with extension_loaded('yaml') and fall back to another adapter when absent

Example fix

// before
$config = new \Phalcon\Config\Adapter\Yaml(dirname(__DIR__) . '/config/app.yaml');

// after
$path = dirname(__DIR__) . '/config/app.yaml';
$config = extension_loaded('yaml')
    ? new \Phalcon\Config\Adapter\Yaml($path)
    : new \Phalcon\Config\Adapter\Ini(preg_replace('/\.ya?ml$/', '.ini', $path));

if (!extension_loaded('yaml')) {
    throw new RuntimeException(
        'ext-yaml is required for the Yaml config adapter; install with: pecl install yaml'
    );
}
$config = new \Phalcon\Config\Adapter\Yaml($path);

When it happens

Trigger: Using new Yaml('app.yaml') on a machine where ext-yaml is not installed or not enabled — most default PHP builds and minimal Docker/CI images do not include it; the CLI SAPI using a different php.ini without the extension.

Common situations: Works on the dev machine but fails in Docker/CI/production; apt/pecl extension installed for the web SAPI but the extension line missing for CLI; upgrading PHP images and losing the custom extension.

Related errors

• YamlLoader requires the "yaml" PHP extension (pecl/yaml)
• Configuration file {fileName} cannot be loaded
• This class requires the openssl extension for PHP
• This class requires the gettext extension for PHP
• To use 'array' adapter you have to specify the 'config' as a

AI-assisted analysis of phalcon/cphalcon@b7419de9cd (2026-08-21). Data as JSON: /api/errors/bb5b631db1eac80f. Report an issue: GitHub.