cakephp/cakephp · error · InvalidArgumentException

Invalid format to Message-ID. The text should be something…

Error message

Invalid format to Message-ID. The text should be something like "<uuid@server.com>"

What it means

Message::setMessageId() accepts either bool or a string; a string must match /^<.+@.+>$/ i.e. angle-bracketed Message-ID like '<uuid@server.com>'. Anything else throws InvalidArgumentException. This ensures a standards-compliant RFC Message-ID header.

Solutions

1. Wrap the id in angle brackets: setMessageId('<' . $uuid . '@example.com>')
2. Pass true/false if you only want default/auto behavior
3. Validate against the regex /^<.+@.+>$/ before calling

Example fix

// before
$message->setMessageId($uuid . '@server.com');
// after
$message->setMessageId('<' . $uuid . '@server.com>');

if (!(is_bool($id) || (is_string($id) && preg_match('/^<.+@.+>$/', $id)))) {
    throw new \InvalidArgumentException('Message-ID must be bool or "<local@domain>"');
}
$message->setMessageId($id);

function isValidMessageId(mixed $id): bool {
    return is_bool($id) || (is_string($id) && preg_match('/^<.+@.+>$/', $id) === 1);
}

try {
    $message->setMessageId($id);
} catch (\InvalidArgumentException $e) {
    $message->setMessageId(true); // fall back to auto-generated ID
}

When it happens

Trigger: setMessageId('uuid@server.com') (missing < >), setMessageId('my-id'), or passing a bare UUID. Called during testSend/testSendHeadersStripCrlf flows.

Common situations: Developers generating a UUID and forgetting to wrap it in < >; copying Message-ID values without brackets from email clients; building ids from variables containing spaces/newlines.

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

• Could not send email
• File must be a filepath or UploadedFileInterface instance…
• File not found
• Format not available.
• Invalid message type

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

Appendix: source

Thrown at src/Mailer/Message.php:1077

        return [$format];
    }

    /**
     * Sets message ID.
     *
     * @param string|bool $message True to generate a new Message-ID, False to ignore (not send in email),
     *   String to set as Message-ID.
     * @return $this
     * @throws \InvalidArgumentException
     */
    public function setMessageId(string|bool $message)
    {
        if (is_bool($message)) {
            $this->messageId = $message;
        } else {
            if (!preg_match('/^\<.+@.+\>$/', $message)) {
                throw new InvalidArgumentException(
                    'Invalid format to Message-ID. The text should be something like "<uuid@server.com>"',
                );
            }
            $this->messageId = $message;
        }

        return $this;
    }

    /**
     * Gets message ID.
     *
     * @return string|bool
     */
    public function getMessageId(): string|bool
    {
        return $this->messageId;
    }

View on GitHub (pinned to 1128eba9b0)