telegram bot is not running (check token and chat ID)

Error message

telegram bot is not running (check token and chat ID)

What it means

Returned by the SetTestTgFunc closure in web.go — the handler behind the panel's Telegram test endpoint. It fires before any API call when tgbotService.IsRunning() is false: the bot process/handle was never started, because the Telegram setting is disabled or Start() failed on an invalid token or missing chat ID.

Source

Thrown at internal/web/web.go:623

			s.bus.Publish(eventbus.Event{
				Type: eventbus.EventXrayCrash,
				Data: err.Error(),
			})
		}
	}

	// Register email subscriber (always — it checks smtpEnable at runtime)
	emailService := email.NewEmailService(s.settingService)
	emailSub := email.NewSubscriber(s.settingService, emailService)
	s.bus.Subscribe("email-notifier", emailSub.HandleEvent)

	// Wire email service to controller for test endpoint
	controller.SetEmailService(emailService)

	// Wire Telegram test function to controller
	controller.SetTestTgFunc(func() error {
		if !s.tgbotService.IsRunning() {
			return fmt.Errorf("telegram bot is not running (check token and chat ID)")
		}
		if err := s.tgbotService.TestConnection(); err != nil {
			return fmt.Errorf("telegram API test failed: %w", err)
		}
		s.tgbotService.SendMsgToTgbotAdmins("✅ Test message from 3x-ui")
		return nil
	})

	controller.SetReloadTgbotFunc(func() {
		enabled, err := s.settingService.GetTgbotEnabled()
		if err != nil || !enabled {
			if s.tgbotService.IsRunning() {
				s.tgbotService.Stop()
			}
			if s.bus != nil {
				s.bus.Unsubscribe("tg-notifier")
			}
			return

View on GitHub (pinned to ad32144c42)

Solutions

Fill in botToken (from @BotFather) AND chatId (the admin chat the bot was started in), and enable the bot in settings, then Save — saving reloads the bot.
After saving, check panel logs for a successful bot start before pressing Test.
If it persists with correct settings, check the tgbot job/Start() logs — the underlying failure is usually visible there (network to Telegram, 401).

Example fix

// before: bot disabled + test pressed -> error
// settings: tgbotEnable=false, botToken="", chatId=""

// after: settings saved with
// tgbotEnable=true, botToken="123456:ABC..." (from @BotFather), chatId="<your chat id>"
// then press Test

Defensive patterns

Strategy: validation

Validate before calling

// Before invoking the test, ensure the bot is configured and running
enabled, _ := settingSvc.GetTgbotEnabled()
if !enabled || !tgbotSvc.IsRunning() {
    return errors.New("enable the telegram bot and set token/chat ID first")
}

Type guard

null

Try / catch

if err := testTg(); err != nil {
    if strings.Contains(err.Error(), "not running") {
        // guide user to settings; no retry
    }
}

Prevention

Treat token + chatId + enable as one unit when saving Telegram settings.
Confirm bot start in logs before testing.

When it happens

Trigger: Clicking 'Test' on the Telegram settings page while tgbotEnable is off, botToken is empty/malformed, chatId is unset, or the bot previously crashed and was stopped.

Common situations: First-time Telegram setup where the admin pastes the token but forgets chatId or the enable toggle; toggling the bot off then testing; a previously-started bot stopped after a token error.

Related errors

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