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

You must provide 'filePath' option in factory config paramet

Error message

You must provide 'filePath' option in factory config parameter.

What it means

When the factory config is given as an array, checkConfigArray() requires a 'filePath' key before any adapter is constructed. If it is absent, MissingConfigOption('filePath') is thrown — the message names the exact missing option.

Source

Thrown at phalcon/Config/ConfigFactory.zep:223

        if typeof config !== "array" {
            throw new ConfigNotArrayOrObject();
        }

        this->checkConfigArray(config);

        return config;
    }

    /**
     * @param array $config
     *
     * @throws Exception
     */
    private function checkConfigArray(array config) -> void
    {
        if true !== isset(config["filePath"]) {
            throw new MissingConfigOption("filePath");
        }

        if true !== isset(config["adapter"]) {
            throw new MissingConfigOption("adapter");
        }
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Use exactly 'filePath' (camelCase) together with 'adapter'
2. Validate keys with array_key_exists('filePath', $config) before calling load()
3. When migrating from Phalcon 3-era configs, rename snake_case keys to camelCase

Example fix

// before
$config = $factory->load(['adapter' => 'ini', 'file_path' => '/etc/app.ini']);

// after
$config = $factory->load([
    'adapter'  => 'ini',
    'filePath' => '/etc/app.ini',
]);

foreach (['filePath', 'adapter'] as $key) {
    if (!array_key_exists($key, $configArray)) {
        throw new InvalidArgumentException(
            sprintf('ConfigFactory config is missing the "%s" key', $key)
        );
    }
}
$config = $factory->load($configArray);

try {
    $config = $factory->load($configArray);
} catch (\Phalcon\Config\ConfigFactory\Exception\MissingConfigOption $e) {
    // Message names the missing option ('filePath'); supply it and retry
    $configArray['filePath'] ??= '/etc/myapp/config.ini';
    $config = $factory->load($configArray);
}

When it happens

Trigger: $factory->load(['adapter' => 'ini']) with no filePath; keys named 'file', 'path', or snake_case 'file_path' are not recognized and the check still fails.

Common situations: Porting config arrays written for other Phalcon factories with different key names; camelCase vs snake_case mismatch in configs migrated from older setups; a key silently dropped during array merging.

Understand the failure class

Background: Config validation failed: what "invalid value for {key}" and settings-rejection errors mean across 19 open-source libraries — this error's family across 19 libraries.

Related errors

• You must provide 'adapter' option in factory config paramete
• You need to provide the extension in the file path
• Config must be array or Phalcon\Config\Config object
• To use 'array' adapter you have to specify the 'config' as a
• Configuration file {fileName} cannot be loaded

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