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

Invalid data type for merge.

Error message

Invalid data type for merge.

What it means

Config::merge() accepts only an array or an object implementing Phalcon\Config\ConfigInterface. Scalars are rejected outright, and so are plain objects — a stdClass with config-like keys still throws InvalidMergeData because the object branch is guarded by instanceof ConfigInterface.

Source

Thrown at phalcon/Config/Config.zep:92

     *
     * $globalConfig->merge($appConfig);
     *```
     *
     * @param array|ConfigInterface $toMerge
     *
     * @return ConfigInterface
     * @throws Exception
     */
    public function merge(var toMerge) -> <ConfigInterface>
    {
        var result, source, target;

        if typeof toMerge === "array" {
            let target = toMerge;
        } elseif typeof toMerge === "object" && toMerge instanceof ConfigInterface {
            let target = toMerge->toArray();
        } else {
            throw new InvalidMergeData();
        }

        let source = this->toArray();

        this->clear();

        let result = this->internalMerge(source, target);

        this->init(result);

        return this;
    }

    /**
     * Returns a value from current config using a dot separated path.
     *
     *```php
     * echo $config->path("unknown.path", "default", ".");

View on GitHub (pinned to b7419de9cd)

Solutions

1. Decode JSON with assoc: json_decode($json, true)
2. Wrap arrays in a Config instance: $config->merge(new Config($array))
3. Cast plain objects before merging: $config->merge((array) $object)

Example fix

// before
$config->merge(json_decode($rawJson));

// after
$config->merge(json_decode($rawJson, true));

if (!is_array($toMerge) && !$toMerge instanceof \Phalcon\Config\ConfigInterface) {
    throw new InvalidArgumentException(sprintf(
        'Config::merge() needs array or ConfigInterface, %s given',
        gettype($toMerge)
    ));
}
$config->merge($toMerge);

/**
 * merge() accepts arrays and ConfigInterface objects only;
 * stdClass and scalars are rejected even when they look like config.
 */
function isMergeableConfig($value): bool
{
    return is_array($value) || $value instanceof \Phalcon\Config\ConfigInterface;
}

try {
    $config->merge($incoming);
} catch (\Phalcon\Config\Config\Exception\InvalidMergeData $e) {
    // Coerce common object payloads and retry
    if (is_object($incoming)) {
        $config->merge((array) $incoming);
    }
}

When it happens

Trigger: $config->merge(json_decode($json)) — stdClass because the assoc argument was omitted; $config->merge('production'); merging a SimpleXML or stdClass payload from an API.

Common situations: Decoding JSON without true as the second argument; merging data from sources that return objects (APIs, SimpleXML); merging env-derived values that are plain strings.

Understand the failure class

Background: Invalid argument type errors: "must be of type string", "expected X, got Y", and ERR_INVALID_ARG_TYPE explained — this error's family across 15 libraries.

Related errors

• 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
• Configuration file {fileName} cannot be loaded
• Configuration file {fileName} cannot be loaded

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