// troubleshooting guide · gitea

Gitea Email Notifications Not Sending (SMTP Error)

Status
Workaround available
platforms:
Self-hosted
updated:
November 16, 2026
reports:
3
Method
how we research
Share

RUNBOOK · gitea/email-not-sending4 FIXES

// quick answer

Enable notification mail, then match the SMTP port to the right protocol: implicit TLS on 465, STARTTLS on 587.

Most likely fix: Enable notify mail

How to fix it

// try these in order, the most common fix is first

  1. FIX 1Enable notify mail

    1. 01In app.ini [service] set ENABLE_NOTIFY_MAIL = true
    2. 02Restart Gitea
    Did this fix it?
  2. FIX 2Fix TLS pairing

    1. 01In [mailer] set PROTOCOL = smtps for port 465 or smtp+starttls for 587/2525
    Did this fix it?
  3. FIX 3EOF on newer versions

    1. 01Try ENABLE_HELO = false in [mailer]
    Did this fix it?
  4. FIX 4Check user settings

    1. 01Confirm each user has a primary email and notification preferences enabled
    Did this fix it?

SANDBOX · gitea RUNS IN YOUR BROWSER

Try it: push, review, run CI and merge in a code host and cloud workspace

A hands-on Gitea-style sandbox, including the spots where users get stuck. See where problems like this one start. 1-2 minutes, nothing is saved.

Symptoms

Test email works but no notifications arrive, or errors like first record does not look like a TLS handshake or could not initiate SMTP session: EOF.

Why it happens

  • C-01ENABLE_NOTIFY_MAIL not set
  • C-02Port and TLS mode mismatch
  • C-03HELO problems on newer versions
  • C-04Missing primary email or user notification settings
  • C-05Sendmail path or exit status errors

// this guide also covers

  • gitea not sending emails
  • gitea smtp error
  • gitea mailer tls handshake

Still not working?

If Gitea keeps failing, you're not alone. See every Gitea problem users report or the alternatives people switch to.

Have an app idea? Our small team builds any software: web and mobile apps, games, desktop, AI tools. Price agreed together.

Talk to us

Watch Gitea Get an email when its price changes, it has an outage, or we publish a new fix. No spam.

Fixed it? Share this guide

Other Gitea errors

All 11 Gitea errors and fixes →