MHSanaei/3x-ui · warning

email service not available

Error message

email service not available

What it means

The testSmtp handler checks the package-level emailService singleton and reports it is nil — the SMTP service was never constructed at startup. The service is only initialized when the email configuration in the database is complete/valid enough to build a client, so this error usually means email settings (host, port, sender) were never saved or failed initialization during boot.

Source

Thrown at internal/web/controller/setting.go:274

}

func (a *SettingController) setApiTokenEnabled(c *gin.Context) {
	id, err := strconv.Atoi(c.Param("id"))
	if err != nil {
		jsonMsg(c, I18nWeb(c, "pages.settings.toasts.modifySettings"), err)
		return
	}
	form := &apiTokenEnabledForm{}
	if bindErr := c.ShouldBind(form); bindErr != nil {
		jsonMsg(c, I18nWeb(c, "pages.settings.toasts.modifySettings"), bindErr)
		return
	}
	jsonMsg(c, I18nWeb(c, "pages.settings.toasts.modifySettings"), a.apiTokenService.SetEnabled(id, form.Enabled))
}

func (a *SettingController) testSmtp(c *gin.Context) {
	if emailService == nil {
		jsonMsg(c, I18nWeb(c, "pages.settings.smtpNotInitialized"), errors.New("email service not available"))
		return
	}
	logger.Info("SMTP test: starting...")
	result := emailService.TestConnection()
	if !result.Success {
		logger.Warning("SMTP test failed at", result.Stage+":", result.Message)
		c.JSON(200, gin.H{
			"success": false,
			"stage":   result.Stage,
			"msg":     result.Message,
		})
		return
	}
	logger.Info("SMTP test: success")
	c.JSON(200, gin.H{
		"success": true,
		"stage":   result.Stage,
		"msg":     result.Message,

View on GitHub (pinned to ad32144c42)

Solutions

1. Fill in and SAVE the SMTP settings first, then retry the test button
2. Restart the panel after saving so the startup path constructs emailService
3. Check panel logs for an email-service init error at boot if settings look correct

When it happens

Trigger: Clicking 'test SMTP' in settings before saving any SMTP configuration; saving config that fails service construction (missing host/port); a startup ordering issue where the settings job that builds emailService has not run yet.

Common situations: Fresh installs; admins editing SMTP JSON directly in the DB; restart loops that skip the init job.

Related errors

• bot not started
• database is not initialized
• The current username or password is invalid
• The new username and password are empty
• telegram bot disabled

AI-assisted analysis of MHSanaei/3x-ui@ad32144c42 (2026-08-15). Data as JSON: /api/errors/6c77c5627ea4bf38. Report an issue: GitHub.