flarum/framework · error · ValidationFailed

You must enter a valid email.

Error message

You must enter a valid email.

What it means

During installation, AdminUser::validate() checks the admin email with filter_var(FILTER_VALIDATE_EMAIL). An email that fails that check causes ValidationFailed('You must enter a valid email.'). The constructor runs this validation immediately, so an invalid email aborts object creation.

Solutions

1. Provide a syntactically valid email (must contain a local part, @, and domain) to the installer
2. Pre-validate the email field in the installer UI before submission
3. Trim whitespace from input before constructing AdminUser

Example fix

// before
new AdminUser('admin', 'not-an-email', 'secret');
// after
$email = filter_var(trim($email), FILTER_VALIDATE_EMAIL);
if ($email === false) { /* re-prompt */ }
new AdminUser('admin', $email, 'secret');

if (filter_var(trim($email), FILTER_VALIDATE_EMAIL) === false) {
    throw new ValidationFailed('Please enter a valid email address.');
}

function isValidEmail(?string $email): bool { return $email !== null && filter_var(trim($email), FILTER_VALIDATE_EMAIL) !== false; }

try {
    $admin = new AdminUser($username, $email, $password);
} catch (ValidationFailed $e) {
    $form->addError('email', $e->getMessage());
}

When it happens

Trigger: Constructing AdminUser with an empty, malformed, or whitespace-containing email during web or console installation.

Common situations: Installer form submitted with a blank or mistyped email (missing @, spaces, trailing punctuation); automated installs with placeholder emails like 'admin' or 'changeme'.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• Username can only contain letters, numbers, underscores…
• This value is required
• The admin password did not match its confirmation.
• Please specify a database driver.
• Both text and html views must be provided to send an email…

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

Appendix: source

Thrown at framework/core/src/Install/AdminUser.php:44

    {
        return $this->username;
    }

    public function getAttributes(): array
    {
        return [
            'username' => $this->username,
            'email' => $this->email,
            'password' => (new BcryptHasher)->make($this->password),
            'joined_at' => Carbon::now(),
            'is_email_confirmed' => 1,
        ];
    }

    private function validate(): void
    {
        if (! filter_var($this->email, FILTER_VALIDATE_EMAIL)) {
            throw new ValidationFailed('You must enter a valid email.');
        }

        if (! $this->username || preg_match('/[^a-z0-9_-]/i', $this->username)) {
            throw new ValidationFailed('Username can only contain letters, numbers, underscores, and dashes.');
        }
    }
}

View on GitHub (pinned to 4b939f6853)