roa2web-service-auto/deployment/windows/docs/TELEGRAM_BOT_TROUBLESHOOTING.md

ROA2WEB Telegram Bot - Windows Deployment Troubleshooting Guide

⚠️ DEPRECATED ARCHITECTURE

This documentation refers to the OLD microservices architecture (port 8002). The current architecture is an ultrathin monolith - everything on port 8000/8001. Telegram internal API is now at /api/telegram/internal/* on the main backend.

This guide helps diagnose and fix common issues with Telegram bot integration on Windows Server deployments.

Problem: "Link invalid sau expirat" (Invalid or expired link)

When users generate a linking code in the web frontend but the Telegram bot says the code is invalid or expired, this indicates a communication problem between the backend and telegram bot services.

Root Cause

The backend cannot communicate with the Telegram bot's internal API to save the generated linking codes.

Diagnostic Steps

Run these PowerShell commands on the Windows Server (10.0.20.36) to diagnose:

1. Check Telegram Bot Service Status

# Check if service is running
Get-Service ROA2WEB-TelegramBot

# Expected output:
# Status   Name                    DisplayName
# ------   ----                    -----------
# Running  ROA2WEB-TelegramBot     ROA2WEB Telegram Bot Service

If service is not running, start it:

cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Start-TelegramBot.ps1

2. Check Internal API Port (8002)

# Check if port 8002 is listening
netstat -ano | findstr :8002

# Expected output (should show LISTENING):
# TCP    127.0.0.1:8002    0.0.0.0:0    LISTENING    <PID>

If port is not listening, the telegram bot service may not have started correctly. Check logs:

# View service logs
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Tail 50

# View error logs
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 50

3. Test Internal API Health Endpoint

# Test if internal API responds
Invoke-WebRequest http://localhost:8002/internal/health

# Expected output:
# StatusCode        : 200
# StatusDescription : OK
# Content           : {"status":"healthy","timestamp":"2025-...","database_stats":{...}}

If this fails, the internal API is not running. Check telegram bot service logs.

4. Check Backend .env Configuration

# View backend .env file
notepad C:\inetpub\wwwroot\roa2web\backend\.env

# Look for this line:
# TELEGRAM_BOT_INTERNAL_API=http://localhost:8002

If the line is missing or incorrect, add/fix it:

TELEGRAM_BOT_INTERNAL_API=http://localhost:8002

Then restart backend service:

Restart-Service ROA2WEB-Backend

5. Check Telegram Bot .env Configuration

# View telegram bot .env file
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env

# Verify these settings:
# TELEGRAM_BOT_TOKEN=<your_production_bot_token>
# BACKEND_URL=http://localhost:8000
# INTERNAL_API_PORT=8002
# INTERNAL_API_HOST=127.0.0.1

If TELEGRAM_BOT_TOKEN is wrong (e.g., still using DEV token), update it and restart:

cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Restart-TelegramBot.ps1

6. Test Full Linking Flow

# 1. Test backend can reach telegram bot internal API
Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/save-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"TEST1234","telegram_user_id":0,"oracle_username":"testuser","expires_in_minutes":15}'

# Expected output:
# StatusCode: 201 (Created)
# Content: {"success":true,"code":"TEST1234","expires_at":"...","message":"..."}

# 2. Verify code was saved
Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/verify-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"TEST1234"}'

# Expected output:
# StatusCode: 200 (OK)
# Content: {"valid":true,"oracle_username":"testuser","message":"Code is valid"}

If step 1 fails, there's a network/firewall issue blocking localhost:8002.

Solution Checklist

Fix the issue by following this checklist in order:

• Telegram bot service is running

  Get-Service ROA2WEB-TelegramBot
  # If stopped: cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts; .\Start-TelegramBot.ps1
  

• Internal API port 8002 is listening

  netstat -ano | findstr :8002
  # Should show LISTENING on 127.0.0.1:8002
  

• Internal API responds to health checks

  Invoke-WebRequest http://localhost:8002/internal/health
  # Should return 200 OK with status "healthy"
  

• Backend .env has TELEGRAM_BOT_INTERNAL_API configured

  notepad C:\inetpub\wwwroot\roa2web\backend\.env
  # Add: TELEGRAM_BOT_INTERNAL_API=http://localhost:8002
  

• Backend service restarted after .env changes

  Restart-Service ROA2WEB-Backend
  

• Telegram bot .env has correct TELEGRAM_BOT_TOKEN

  notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
  # Should have ROA2WEBBot token, not ROA2WEBDEVBot token
  

• Test full linking flow from web frontend

  • Log in to web frontend (http://10.0.20.36)
  • Generate linking code
  • Send code to @ROA2WEBBot via /start CODE12345
  • Should receive success message from bot

---

Problem: "Cannot connect to backend" / Connection Errors

After successfully generating a linking code, the Telegram bot finds the code but fails to complete the linking with error messages like:

• httpcore.ConnectError: All connection attempts failed
• Cannot connect to backend at http://localhost:8000
• AttributeError: 'ConnectError' object has no attribute 'response' (fixed in latest version)

Root Cause

The Telegram bot cannot communicate with the FastAPI backend to verify the Oracle user and obtain a JWT token. This happens when:

1. Backend service is not running
2. Backend is running on wrong port
3. BACKEND_URL in telegram bot .env is incorrect
4. Firewall blocking communication

Diagnostic Steps

1. Check Backend Service Status

# Check if backend service is running
Get-Service ROA2WEB-Backend

# Expected output:
# Status   Name              DisplayName
# ------   ----              -----------
# Running  ROA2WEB-Backend   ROA2WEB Backend Service

If service is not running, start it:

cd C:\inetpub\wwwroot\roa2web\scripts
.\Start-ROA2WEB.ps1

2. Check Backend Port (8000)

# Check if port 8000 is listening
netstat -ano | findstr :8000

# Expected output (should show LISTENING):
# TCP    0.0.0.0:8000    0.0.0.0:0    LISTENING    <PID>

If port is not listening, check backend logs:

# View backend service logs
Get-Content C:\inetpub\wwwroot\roa2web\backend\logs\*.log -Tail 50

3. Test Backend Health Endpoint

# Test if backend API responds
Invoke-WebRequest http://localhost:8000/health

# Expected output:
# StatusCode        : 200
# Content           : {"status":"healthy",...}

If this fails, backend is not accessible. Check service logs.

4. Check Telegram Bot BACKEND_URL Configuration

# View telegram bot .env file
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env

# Verify this line exists and is correct:
# BACKEND_URL=http://localhost:8000

Common mistakes:

• Using http://localhost:8001 (dev port instead of production port 8000)
• Missing http:// prefix
• Using IP address instead of localhost

If BACKEND_URL is incorrect, fix it and restart:

cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Restart-TelegramBot.ps1

5. Test Backend Verify-User Endpoint

# Test the specific endpoint telegram bot uses
Invoke-WebRequest -Method POST -Uri http://localhost:8000/api/telegram/auth/verify-user `
  -Headers @{"Content-Type"="application/json"} `
  -Body '{"linking_code":"TESTCODE","oracle_username":"testuser"}'

# Expected output (will fail with 400/404 for test data, but confirms endpoint is reachable):
# StatusCode: 400 or 404 (NOT connection error)

If you get connection error instead of 400/404, backend is not running or port is wrong.

Solution Checklist

Fix the issue by following this checklist:

• Backend service is running

  Get-Service ROA2WEB-Backend
  # If stopped: cd C:\inetpub\wwwroot\roa2web\scripts; .\Start-ROA2WEB.ps1
  

• Backend port 8000 is listening

  netstat -ano | findstr :8000
  # Should show LISTENING on 0.0.0.0:8000
  

• Backend health check responds

  Invoke-WebRequest http://localhost:8000/health
  # Should return 200 OK
  

• Telegram bot .env has correct BACKEND_URL

  notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env
  # Must be: BACKEND_URL=http://localhost:8000
  

• Telegram bot service restarted after .env changes

  cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
  .\Restart-TelegramBot.ps1
  

• Test full linking flow

  • Generate code in web frontend
  • Send code to @ROA2WEBBot: /start CODE12345
  • Should receive success message (not connection error)

---

Common Issues

Issue 1: Port 8002 Already in Use

Symptoms:

• Telegram bot service fails to start
• Logs show "Address already in use" or "Port 8002 is already allocated"

Solution:

# Find process using port 8002
netstat -ano | findstr :8002

# Kill the process (replace <PID> with actual process ID)
taskkill /PID <PID> /F

# Restart telegram bot service
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Restart-TelegramBot.ps1

Issue 2: Firewall Blocking Localhost

Symptoms:

• Backend cannot reach http://localhost:8002
• Connection timeout errors in backend logs

Solution:

# Add firewall rule for port 8002 (localhost only)
New-NetFirewallRule -DisplayName "ROA2WEB Telegram Bot Internal API" -Direction Inbound -LocalPort 8002 -Protocol TCP -Action Allow -LocalAddress 127.0.0.1

Issue 3: Wrong Bot Token

Symptoms:

• Telegram bot service runs but doesn't respond to commands
• Logs show "Unauthorized" or "Invalid bot token"

Solution:

# Update .env with correct token from @BotFather
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env

# Change TELEGRAM_BOT_TOKEN to production bot token:
# TELEGRAM_BOT_TOKEN=<production_bot_token>

# Restart service
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Restart-TelegramBot.ps1

Issue 4: SQLite Database Locked

Symptoms:

• Telegram bot logs show "database is locked" errors
• Commands fail intermittently

Solution:

# Stop service
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Stop-TelegramBot.ps1

# Wait 10 seconds for locks to release
Start-Sleep -Seconds 10

# Start service
.\Start-TelegramBot.ps1

Issue 5: Backend Service Not Running

Symptoms:

• Telegram bot logs show "Cannot connect to backend" errors
• httpcore.ConnectError: All connection attempts failed
• Linking codes are found but linking fails

Solution:

# Check backend service status
Get-Service ROA2WEB-Backend

# If stopped, start it
cd C:\inetpub\wwwroot\roa2web\scripts
.\Start-ROA2WEB.ps1

# Verify backend is listening on port 8000
netstat -ano | findstr :8000

# Test backend health
Invoke-WebRequest http://localhost:8000/health

Check backend logs for startup errors:

Get-Content C:\inetpub\wwwroot\roa2web\backend\logs\*.log -Tail 50

Common backend startup issues:

• Oracle database not accessible
• Missing environment variables in backend .env
• Port 8000 already in use by another process
• Python dependencies not installed

Issue 6: Wrong Backend URL in Telegram Bot

Symptoms:

• Connection errors to backend
• Logs show wrong URL (e.g., http://localhost:8001 instead of http://localhost:8000)

Solution:

# Edit telegram bot .env
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env

# Ensure this line is correct:
# BACKEND_URL=http://localhost:8000
# (Production uses port 8000, not 8001 which is dev port)

# Restart telegram bot service
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Restart-TelegramBot.ps1

Verification Steps

After fixing, verify the complete flow works:

1. Backend can save codes to telegram bot:

   Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/save-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"VERIFY01","telegram_user_id":0,"oracle_username":"testuser","expires_in_minutes":15}'
   

   Expected: 201 Created with success message

2. Telegram bot can verify codes:

   Invoke-WebRequest -Method POST -Uri http://localhost:8002/internal/verify-code -Headers @{"Content-Type"="application/json"} -Body '{"code":"VERIFY01"}'
   

   Expected: 200 OK with "valid":true

3. End-to-end test from web frontend:

   • Open web app: http://10.0.20.36
   • Login with Oracle credentials
   • Click "Link Telegram Account"
   • Copy the 8-character code
   • Send to @ROA2WEBBot: /start CODE12345
   • Should receive: "Contul tău Telegram a fost asociat cu succes!"

Getting Help

If issues persist after following this guide:

1. Collect diagnostic information:

   # Service status
   Get-Service ROA2WEB-TelegramBot | Format-List *
   
   # Port listening
   netstat -ano | findstr :8002
   
   # Recent logs (last 100 lines)
   Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Tail 100
   Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stderr.log -Tail 100
   
   # Backend logs
   Get-Content C:\inetpub\wwwroot\roa2web\backend\logs\*.log -Tail 100
   

2. Check configuration files:

   # Backend .env (sanitize sensitive data before sharing!)
   Get-Content C:\inetpub\wwwroot\roa2web\backend\.env
   
   # Telegram bot .env (sanitize bot token before sharing!)
   Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\.env
   

3. Contact support with the collected diagnostic information.

---

Quick Reference Commands

Service Management

# Check status
Get-Service ROA2WEB-TelegramBot

# Start
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Start-TelegramBot.ps1

# Stop
.\Stop-TelegramBot.ps1

# Restart
.\Restart-TelegramBot.ps1

Monitoring

# Watch logs in real-time
Get-Content C:\inetpub\wwwroot\roa2web\telegram-bot\logs\stdout.log -Wait -Tail 50

# Check health
Invoke-WebRequest http://localhost:8002/internal/health

# Check database stats
Invoke-WebRequest http://localhost:8002/internal/stats

Configuration

# Edit backend config
notepad C:\inetpub\wwwroot\roa2web\backend\.env

# Edit telegram bot config
notepad C:\inetpub\wwwroot\roa2web\telegram-bot\.env

# Restart after changes
Restart-Service ROA2WEB-Backend
cd C:\inetpub\wwwroot\roa2web\telegram-bot\scripts
.\Restart-TelegramBot.ps1