cakephp/cakephp · error · InvalidArgumentException

Unknown deferrable passed:

Error message

Unknown deferrable passed: 

What it means

ForeignKey::normalizeDeferrable() maps human-readable deferrable mode strings (e.g. 'deferrable', 'not_deferrable', 'initially_deferred', 'initially_immediate' — case-insensitive, underscores converted to spaces) to normalized values via a mapping array. Any input whose normalized form is not a key of the mapping throws InvalidArgumentException.

Solutions

1. Use one of the recognized strings: 'deferrable', 'not deferrable', 'initially deferred', 'initially immediate' (underscores also accepted)
2. Check the exception message to see the exact value you passed and correct it
3. Inspect the $mapping array in normalizeDeferrable() to see all accepted inputs

Example fix

// before
$foreignKey->setDeferrable('deferred');
// after
$foreignKey->setDeferrable('initially deferred');

$valid = ['deferrable', 'not deferrable', 'initially deferred', 'initially immediate'];
$norm = strtolower(str_replace('_', ' ', $deferrable));
if (!in_array($norm, $valid, true)) {
    throw new InvalidArgumentException('Invalid deferrable mode: ' . $deferrable);
}
$fk->setDeferrable($deferrable);

try {
    $fk->setDeferrable($mode);
} catch (\InvalidArgumentException $e) {
    // fall back to default mode and log
    $logger->warning('Bad deferrable mode: ' . $e->getMessage());
}

When it happens

Trigger: Calling setDeferrable('defered') (typo), setDeferrable('deferred') (missing the 'initially' prefix where required), or passing arbitrary strings to the constructor's deferrable option.

Common situations: Typos in deferrable mode names; assuming 'deferred' alone is valid when only 'initially deferred'/'initially immediate' are; copying Postgres DDL strings with formats the mapping does not recognize.

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

• Invalid value for "on":
• Unknown action passed:
• Check constraint expression cannot be empty
• Delete action is invalid. Must be one of
• References must contain a table and column.

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

Appendix: source

Thrown at src/Database/Schema/ForeignKey.php:265

     * @throws \InvalidArgumentException
     * @return string
     */
    protected function normalizeDeferrable(string $deferrable): string
    {
        $mapping = [
            'DEFERRED' => ForeignKey::DEFERRED,
            'IMMEDIATE' => ForeignKey::IMMEDIATE,
            'NOT DEFERRED' => ForeignKey::NOT_DEFERRED,
            ForeignKey::DEFERRED => ForeignKey::DEFERRED,
            ForeignKey::IMMEDIATE => ForeignKey::IMMEDIATE,
            ForeignKey::NOT_DEFERRED => ForeignKey::NOT_DEFERRED,
        ];
        $normalized = strtoupper(str_replace('_', ' ', $deferrable));
        if (array_key_exists($normalized, $mapping)) {
            return $mapping[$normalized];
        }

        throw new InvalidArgumentException('Unknown deferrable passed: ' . $deferrable);
    }
}

View on GitHub (pinned to 1128eba9b0)