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

Configuration file {fileName} cannot be loaded

Error message

Configuration file {fileName} cannot be loaded

What it means

After yaml_parse_file(), a null result (empty document) is normalized to an empty array, but a false result — the file could not be read or parsed — throws CannotLoadConfigFile with the basename. So this error means an unreadable file or a YAML parse failure, not an empty one.

Source

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

    {
        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. Check is_file()/is_readable() before constructing
2. Lint the YAML in CI (yaml_parse or a validator) so syntax errors surface at build time
3. Use absolute paths built from __DIR__

Example fix

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

// after
$path = dirname(__DIR__) . '/config/app.yaml';
if (!is_readable($path)) {
    throw new RuntimeException('Missing config file: ' . $path);
}
$config = new \Phalcon\Config\Adapter\Yaml($path);

$path = dirname(__DIR__) . '/config/app.yaml';
if (!is_readable($path)) {
    throw new RuntimeException('Config file missing or unreadable: ' . $path);
}
$config = new \Phalcon\Config\Adapter\Yaml($path);

try {
    $config = new \Phalcon\Config\Adapter\Yaml($path);
} catch (\Phalcon\Config\Adapter\Yaml\Exception\CannotLoadConfigFile $e) {
    // yaml_parse_file() returned false: unreadable file or parse error
    throw new RuntimeException('Failed to load yaml config: ' . $path, 0, $e);
}

When it happens

Trigger: new Yaml('app/config/app.yaml') where the file is missing/unreadable, or the document fails to parse (tabs for indentation, broken syntax after secret substitution).

Common situations: Deploying without the yaml file; templating tools (envsubst-style) leaving invalid YAML behind; tabs or encoding issues introduced by Windows editors.

Related errors

• Configuration file {fileName} cannot be loaded
• Configuration file {fileName} cannot be loaded
• Configuration file {fileName} cannot be loaded
• To use 'array' adapter you have to specify the 'config' as a
• Yaml extension is not loaded

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