// 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
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
FIX 1Enable notify mail
- 01In app.ini [service] set ENABLE_NOTIFY_MAIL = true
- 02Restart Gitea
Did this fix it?FIX 2Fix TLS pairing
- 01In [mailer] set PROTOCOL = smtps for port 465 or smtp+starttls for 587/2525
Did this fix it?FIX 3EOF on newer versions
- 01Try ENABLE_HELO = false in [mailer]
Did this fix it?FIX 4Check user settings
- 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 usOther Gitea errors
- Gitea Actions Jobs Stuck in Waiting (No Matching Runner)
- Gitea SSH Permission Denied (publickey) or Connection Refused
- Gitea 500 Internal Server Error
- Gitea Reverse Proxy Wrong URLs or Redirect Loop (ROOT_URL)
- Gitea Push 413 Request Entity Too Large (LFS Upload Fails)
- Gitea Webhook Not Working (ALLOWED_HOST_LIST Error)
- Why Is Gitea Using So Much Memory or CPU?
- Gitea Upgrade Failed or Database Is Locked