cakephp/cakephp · error · InvalidArgumentException

Invalid merge strategy. Valid options are: `deep`…

Error message

Invalid merge strategy. Valid options are: `deep`, `shallow`.

What it means

ViewBuilder::setConfigMergeStrategy() accepts only the class constants MERGE_DEEP ('deep') or MERGE_SHALLOW ('shallow'). Any other string is rejected with InvalidArgumentException because the strategy controls how ViewBuilder configs are merged and an unknown value would silently change merging semantics.

Solutions

1. Use ViewBuilder::MERGE_DEEP or ViewBuilder::MERGE_SHALLOW constants instead of raw strings
2. Correct the string to exactly 'deep' or 'shallow' (lowercase)
3. Validate/whitelist the value before passing it if it comes from configuration

Example fix

// before
$builder->setConfigMergeStrategy('recursive');
// after
$builder->setConfigMergeStrategy(ViewBuilder::MERGE_DEEP);

$allowed = [ViewBuilder::MERGE_DEEP, ViewBuilder::MERGE_SHALLOW];
if (!in_array($strategy, $allowed, true)) { throw new \InvalidArgumentException('bad strategy'); }
$builder->setConfigMergeStrategy($strategy);

$strategy = in_array($strategy, ['deep','shallow'], true) ? $strategy : ViewBuilder::MERGE_DEEP;

try { $builder->setConfigMergeStrategy($strategy); } catch (\InvalidArgumentException $e) { $builder->setConfigMergeStrategy(ViewBuilder::MERGE_DEEP); }

When it happens

Trigger: Calling $builder->setConfigMergeStrategy('Deep'), 'merge', 'default', or any string other than exactly 'deep' or 'shallow'.

Common situations: Passing a user/config-supplied string; typos or wrong casing; confusing this with other frameworks' merge option names.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Argument 2 is expected to have a `repository` key that…
• Cannot add middleware group
• Cannot add ' ' middleware to group ' '. It has not been…
• Cannot set ` ` value.
• Cannot unset ` ` value.

AI-assisted analysis of cakephp/cakephp@1128eba9b0 (2026-09-12). Data as JSON: /api/errors/5a6d740b28a688dc. Report an issue: GitHub.

Appendix: source

Thrown at src/View/ViewBuilder.php:540

    }

    /**
     * Set the config merge strategy for view options.
     *
     * Can be:
     *  - 'deep': Recursive merge (default for BC, merges nested arrays)
     *  - 'shallow': Simple array merge (replaces array values)
     *
     * This controls how options set via ViewBuilder are merged with
     * the View class's default configuration.
     *
     * @param self::MERGE_DEEP|self::MERGE_SHALLOW $strategy The merge strategy.
     * @return $this
     */
    public function setConfigMergeStrategy(string $strategy)
    {
        if (!in_array($strategy, [self::MERGE_DEEP, self::MERGE_SHALLOW], true)) {
            throw new InvalidArgumentException('Invalid merge strategy. Valid options are: `deep`, `shallow`.');
        }

        $this->_configMergeStrategy = $strategy;

        return $this;
    }

    /**
     * Get the config merge strategy.
     *
     * @return self::MERGE_DEEP|self::MERGE_SHALLOW
     */
    public function getConfigMergeStrategy(): string
    {
        return $this->_configMergeStrategy;
    }

    /**

View on GitHub (pinned to 1128eba9b0)