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

Configuration file {fileName} cannot be loaded

Error message

Configuration file {fileName} cannot be loaded

What it means

Config\Adapter\Json reads the file with file_get_contents(); if that returns false (missing or unreadable file), CannotLoadConfigFile is thrown with the basename. Note that invalid JSON content is a separate failure — it surfaces later in the Json decoder, not from this check.

Source

Thrown at phalcon/Config/Adapter/Json.zep:54

 *```
 */
class Json extends Config
{
    use FileTrait;

    /**
     * Phalcon\Config\Adapter\Json constructor
     *
     * @throws CannotLoadConfigFile
     */
    public function __construct( string filePath)
    {
        var content;

        let content = this->phpFileGetContents(filePath);

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

        parent::__construct(
            (new Decode())->__invoke(content, true)
        );
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Verify the file exists and is readable before loading
2. Use absolute paths built from __DIR__
3. If config is build-generated, fail the build when the file is missing instead of at runtime

Example fix

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

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

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

try {
    $config = new \Phalcon\Config\Adapter\Json($path);
} catch (\Phalcon\Config\Adapter\Json\Exception\CannotLoadConfigFile $e) {
    // Unreadable file (distinct from invalid JSON, which fails in the decoder)
    throw new RuntimeException('Failed to read json config: ' . $path, 0, $e);
}

When it happens

Trigger: new Json('/missing/config.json'); a relative path resolved from a different working directory; a file present but not readable by the PHP process.

Common situations: Deploying without the .json config file; config generated by a build step that did not run; path typos after moving the project root.

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
• Invalid data type for merge.

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