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\Php loads a plain PHP file that returns an array. It first checks is_file(); anything that is not an existing regular file — missing path, a directory, or a dead symlink — throws CannotLoadConfigFile with the basename before require runs.

Source

Thrown at phalcon/Config/Adapter/Php.zep:61

 * use Phalcon\Config\Adapter\Php;
 *
 * $config = new Php("path/config.php");
 *
 * echo $config->phalcon->controllersDir;
 * echo $config->database->username;
 *```
 */
class Php extends Config
{
    /**
     * Phalcon\Config\Adapter\Php constructor
     *
     * @throws CannotLoadConfigFile
     */
    public function __construct( string filePath)
    {
        if unlikely true !== is_file(filePath) {
            throw new CannotLoadConfigFile(basename(filePath));
        }

        parent::__construct(
            require filePath
        );
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Check is_file() on the path before constructing
2. Use absolute paths instead of cwd-relative ones
3. If using environment symlinks, verify the link target ships with the artifact

Example fix

// before
$config = new \Phalcon\Config\Adapter\Php('config/config.php');

// after
$path = dirname(__DIR__) . '/config/config.php';
if (!is_file($path)) {
    throw new RuntimeException('Missing config file: ' . $path);
}
$config = new \Phalcon\Config\Adapter\Php($path);

$path = dirname(__DIR__) . '/config/config.php';
if (!is_file($path)) {
    throw new RuntimeException('Config file missing (not a regular file): ' . $path);
}
$config = new \Phalcon\Config\Adapter\Php($path);

try {
    $config = new \Phalcon\Config\Adapter\Php($path);
} catch (\Phalcon\Config\Adapter\Php\Exception\CannotLoadConfigFile $e) {
    // is_file() failed: missing file, directory, or dead env symlink
    throw new RuntimeException('Failed to load php config: ' . $path, 0, $e);
}

When it happens

Trigger: new Php('config/config.php') where the file is absent; passing a directory path; a config.php symlink whose target (e.g. production.php) was never deployed.

Common situations: config.php excluded from the deploy package or .gitignore; environment-symlink pattern (config.php -> env/prod.php) with the target missing after a partial deploy.

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/2101565ef91c5578. Report an issue: GitHub.