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

To use 'array' adapter you have to specify the 'config' as a

Error message

To use 'array' adapter you have to specify the 'config' as an array.

What it means

In Config\Adapter\Grouped, an entry using 'adapter' => 'array' must carry its actual settings under a 'config' key, because the array adapter reads raw data instead of a file. Without 'config', GroupedAdapterRequiresArray is thrown. Entries without an explicit adapter inherit defaultAdapter, so a default of 'array' combined with file-name entries triggers it too.

Source

Thrown at phalcon/Config/Adapter/Grouped.zep:124

                if "" === defaultAdapter {
                    this->merge(
                        configFactory->load(configName)
                    );

                    continue;
                }

                let configInstance = [
                    "filePath" : configName,
                    "adapter"  : defaultAdapter
                ];
            } elseif !isset configInstance["adapter"] {
                let configInstance["adapter"] = defaultAdapter;
            }

            if "array" === configInstance["adapter"] {
                if !isset configInstance["config"] {
                    throw new GroupedAdapterRequiresArray();
                }

                let configArray    = configInstance["config"],
                    configInstance = new Config(configArray, this->insensitive);
            } else {
                let configInstance = configFactory->load(configInstance);
            }

            this->merge(configInstance);
        }
    }
}

View on GitHub (pinned to b7419de9cd)

Solutions

1. Add the config key: ['adapter' => 'array', 'config' => ['db' => ['host' => 'localhost']]]
2. If the data really lives in a file, use the matching file adapter (ini/json/yaml/php) with filePath instead
3. When using a non-array defaultAdapter, still give array entries an explicit 'adapter' and 'config'

Example fix

// before
new Grouped([
    ['adapter' => 'array', 'filePath' => 'config.php'],
    'app.ini',
]);

// after
new Grouped([
    ['adapter' => 'array', 'config' => ['app' => ['name' => 'cli']]],
    'app.ini',
]);

$entries = [
    ['adapter' => 'array', 'config' => ['app' => ['name' => 'cli']]],
    'app.ini',
];
foreach ($entries as $i => $entry) {
    if (is_array($entry) && ($entry['adapter'] ?? '') === 'array' && !isset($entry['config'])) {
        throw new InvalidArgumentException(sprintf(
            'Grouped entry #%d: the "array" adapter requires a "config" key',
            $i
        ));
    }
}
$config = new \Phalcon\Config\Adapter\Grouped($entries);

try {
    $config = new \Phalcon\Config\Adapter\Grouped($entries);
} catch (\Phalcon\Config\Adapter\Grouped\Exception\GroupedAdapterRequiresArray $e) {
    // An 'array'-adapter entry lacks its 'config' payload; fall back to the file entry alone
    $config = new \Phalcon\Config\Adapter\Grouped(
        array_values(array_filter($entries, 'is_string'))
    );
}

When it happens

Trigger: new Grouped([['adapter' => 'array', 'filePath' => 'config.php']]) — filePath is meaningless here and the required 'config' key is missing. Also new Grouped(['base.ini'], 'array') where the plain file entry inherits 'array' as adapter.

Common situations: Merging file-based entries (ini/yaml) with one in-memory array entry and forgetting the config key; switching a project's defaultAdapter to 'array' while existing entries still only name files.

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

• Configuration file {fileName} cannot be loaded
• Configuration file {fileName} cannot be loaded
• Configuration file {fileName} cannot be loaded
• Configuration file {fileName} cannot be loaded
• Invalid data type for merge.

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