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

Config must be array or Phalcon\Config\Config object

Error message

Config must be array or Phalcon\Config\Config object

What it means

ConfigFactory::load()/parseConfig normalizes its input: a file-path string becomes an adapter+filePath array, and a ConfigInterface object becomes an array via toArray(). Whatever is still not an array afterwards throws ConfigNotArrayOrObject — so integers, floats, booleans, null, and plain (non-Config) objects are rejected.

Source

Thrown at phalcon/Config/ConfigFactory.zep:207

            let oldConfig = config,
                extension = pathinfo(config, PATHINFO_EXTENSION);

            if true  == empty(extension) {
                throw new MissingFileExtension();
            }

            let config = [
                "adapter"  : extension,
                "filePath" : oldConfig
            ];
        }

        if typeof config === "object" && config instanceof ConfigInterface {
            let config = config->toArray();
        }

        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");
        }

View on GitHub (pinned to b7419de9cd)

Solutions

1. Pass one of the three supported forms: a file-path string, an array with filePath+adapter, or a Config instance
2. Check the type before calling load() when the value comes from env/cache/remote sources
3. Use json_decode($raw, true) so decoded data is an array, not stdClass/null

Example fix

// before
$source = $cache->get('app-config'); // null on miss
$config = $factory->load($source);

// after
$source = $cache->get('app-config') ?: '/etc/myapp/config.ini';
if (!is_string($source) && !is_array($source)) {
    throw new InvalidArgumentException('Unsupported config source type');
}
$config = $factory->load($source);

if (!is_string($source) && !is_array($source) && !$source instanceof \Phalcon\Config\ConfigInterface) {
    throw new InvalidArgumentException(sprintf(
        'ConfigFactory expects string path, array config, or ConfigInterface; %s given',
        gettype($source)
    ));
}
$config = $factory->load($source);

/**
 * The factory accepts a file-path string (with extension),
 * an array with filePath/adapter, or a ConfigInterface instance.
 */
function isConfigFactoryInput($value): bool
{
    return is_string($value)
        || is_array($value)
        || $value instanceof \Phalcon\Config\ConfigInterface;
}

try {
    $config = $factory->load($source);
} catch (\Phalcon\Config\ConfigFactory\Exception\ConfigNotArrayOrObject $e) {
    // Source degraded to null/bool/int (cache miss, failed decode); reload from the default path
    $config = $factory->load('/etc/myapp/config.ini');
}

When it happens

Trigger: $factory->load(0), load(true), load(new stdClass()), or load($json) where a failed json_decode returned null.

Common situations: Config paths pulled from getenv() that default to false; a config variable coming back null from a cache miss; passing SimpleXMLElement or stdClass from external sources.

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

• Invalid data type for merge.
• You need to provide the extension in the file path
• You must provide 'filePath' option in factory config paramet
• You must provide 'adapter' option in factory config paramete
• 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/99b58e14df1e9cbc. Report an issue: GitHub.