Skip to main content

Troubleshooting

Diagnose the most common deploy and delivery problems and get mail flowing to your inbox again.

Email Routing Is Not Enabled

Symptom: Deploy stops with Email Routing is not enabled for "example.com".

Cause: Cloudflare Email Routing is off for the zone, so it has no mail records yet.

Solution:

  • Open Email > Email Routing for the domain in the Cloudflare dashboard and enable it.
  • Let Cloudflare add the MX and SPF records it suggests.
  • Run mm deploy again.

API Token Is Missing Permissions

Symptom: Deploy prints API token is missing permissions followed by a list.

Cause: The API token lacks one or more of the three permissions deploy needs.

Solution:

No API Token Found

Symptom: mm deploy fails with No API token found or says the token is invalid or expired.

Cause: The direct command doesn't prompt for a token; it reads CLOUDFLARE_API_TOKEN only.

Solution:

  • Run mm and choose Deploy to set up a token interactively.
  • Or set CLOUDFLARE_API_TOKEN in your environment or a .env file.

Cloudflare Zone Not Found

Symptom: Deploy fails with Failed to find Cloudflare zone.

Cause: The base domain isn't part of a zone the token can see.

Solution:

  • Check that the domain is added to your Cloudflare account and spelled correctly in base_domain.
  • Check that the token's Zone Resources include that zone.

Mail Never Arrives

Symptom: Messages sent to an alias don't show up, and the sender gets no bounce.

Cause: Usually an unverified destination, a drop setting, or a missing deploy.

Solution:

  • Run mm deploy and read the destination warnings; click the verification link Cloudflare emailed to any unverified inbox.
  • Check your spam folder in the real inbox.
  • If unknown_alias_action is drop, confirm the alias exists in the deployed config by running mm alias list, then deploy.
  • Confirm the catch-all in Email > Email Routing > Routing rules points at your Worker.

Sender Gets "Address not found"

Symptom: Mail bounces with Address not found.

Cause: The address isn't a deployed alias, and your unknown alias action is reject.

Solution:

  • Check the spelling with mm alias list.
  • If you created the alias recently, run mm deploy; changes only reach Cloudflare on deploy.
  • With subaddressing off, alias+tag@ is treated as a different address.

Mail Is Refused Unexpectedly

Symptom: Mail bounces with Address is disabled, Address has expired, Sender is blocked, or Sender is not allowed.

Cause: The alias is producing a refusal for that message.

Solution:

  • Run mm alias list to see whether the alias is disabled or expired, then use mm alias enable or mm alias expire <address> never.
  • For sender errors, compare the sender with the alias's rules; *@shop.com doesn't match mail.shop.com.
  • Deploy after any change.

Temporary Configuration Error

Symptom: Every message bounces with Temporary configuration error.

Cause: The Worker couldn't parse or validate its configuration, so it refuses mail rather than guess.

Solution:

  • Run mm validate and fix every reported problem.
  • Run mm deploy to publish the corrected config.

Notifications Are Not Arriving

Symptom: A refusal happens but no notification appears.

Cause: Notifications only fire for known aliases, and failures are silently skipped.

Solution:

  • Run mm notifier list and check that at least one notifier exists and that you deployed after adding it.
  • For an ntfy notifier, check the server URL, topic, and tk_ token. For an ntfy-reverse-proxy notifier, check the context URL and its token.
  • Remember that mail to unknown addresses never notifies.