flarum/framework · error · InvalidArgumentException

The entity must use the EventGeneratorTrait trait in order…

Error message

The entity must use the EventGeneratorTrait trait in order to dispatch events.

What it means

Programming-error guard in DispatchEventsTrait::dispatchEventsFor: the trait releases queued events via $entity->releaseEvents(), which only exists when the entity uses EventGeneratorTrait. Passing an entity without that trait (missing method 'releaseEvents') means its events can never be collected, so an InvalidArgumentException is thrown at development time rather than silently dropping events.

Solutions

1. Add the EventGeneratorTrait to the entity class
2. Ensure you are passing the intended model, not a DTO or wrong object
3. Do not call dispatchEventsFor on entities that never raise domain events

When it happens

Trigger: Thrown at framework/core/src/Foundation/DispatchEventsTrait.php:22 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of flarum/framework@4b939f6853 (2026-09-15). Data as JSON: /api/errors/653b28d79fe94304. Report an issue: GitHub.

Appendix: source

Thrown at framework/core/src/Foundation/DispatchEventsTrait.php:22

 * This file is part of Flarum.
 *
 * For detailed copyright and license information, please view the
 * LICENSE file that was distributed with this source code.
 */

namespace Flarum\Foundation;

use Flarum\User\User;

trait DispatchEventsTrait
{
    /**
     * Dispatch all events for an entity.
     */
    public function dispatchEventsFor(mixed $entity, ?User $actor = null): void
    {
        if (! method_exists($entity, 'releaseEvents')) {
            throw new \InvalidArgumentException(
                'The entity must use the EventGeneratorTrait trait in order to dispatch events.'
            );
        }

        foreach ($entity->releaseEvents() as $event) {
            if (property_exists($event, 'actor') && ! $event->actor) {
                $event->actor = $actor;
            }

            $this->events->dispatch($event);
        }
    }
}

View on GitHub (pinned to 4b939f6853)