cakephp/cakephp · error · UnexpectedValueException

When should be one of "always", "new" or "existing". The…

Error message

When should be one of "always", "new" or "existing". The passed value `%s` is invalid.

What it means

TimestampBehavior::handleEvent() validates the behavior's 'when' configuration on each handled model event; only 'always', 'new' or 'existing' are meaningful modes for deciding when timestamps are refreshed. Any other value (usually a typo in the behavior config) raises UnexpectedValueException.

Solutions

1. Fix the behavior's `events` configuration so each field's `when` value is one of 'always', 'new' or 'existing'.
2. Remove the invalid entry or use the correct string, e.g. 'events' => ['Model.beforeSave' => ['modified' => 'always']].

When it happens

Trigger: Thrown at src/ORM/Behavior/TimestampBehavior.php:105 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at src/ORM/Behavior/TimestampBehavior.php:105

    public function handleEvent(EventInterface $event, EntityInterface $entity): void
    {
        $eventName = $event->getName();
        $events = $this->_config['events'];

        $new = $entity->isNew();
        $refresh = $this->_config['refreshTimestamp'];

        foreach ($events[$eventName] as $field => $when) {
            if (!in_array($when, ['always', 'new', 'existing'], true)) {
                throw new UnexpectedValueException(sprintf(
                    'When should be one of "always", "new" or "existing". The passed value `%s` is invalid.',
                    $when,
                ));
            }
            if (
                $when === 'always' ||
                (
                    $when === 'new' &&
                    $new
                ) ||
                (
                    $when === 'existing' &&
                    !$new
                )
            ) {
                $this->_updateField($entity, $field, $refresh);
            }
        }
    }

View on GitHub (pinned to 1128eba9b0)