TROUBLESHOOTING.md

Ultroid Troubleshooting Guide

Common Issues and Solutions

1. Missing Dependencies

Problem: Addon plugins fail to load due to missing Python packages.

Solution:

• All required dependencies have been added to requirements.txt
• Run: pip install -r requirements.txt
• For Docker: The Dockerfile has been updated to install all dependencies

2. Import Errors

Problem: ImportError: attempted relative import beyond top-level package

Solution:

• Fixed by creating proper addons/__init__.py with correct imports
• Updated addon files to use absolute imports
• Added proper package structure

3. FastAPI Dependency Conflict

Problem: fastapi 0.104.1 requires anyio<4.0.0,>=3.7.1, but you have anyio 4.10.0

Solution:

• Updated requirements.txt to pin anyio version: anyio>=3.7.1,<4.0.0
• This ensures compatibility with FastAPI 0.104.1

4. Telegram Connection Timeouts

Problem: Connection to Telegram failed 5 time(s)

Solutions:

• Check your internet connection
• Verify API credentials in .env file
• Try using a VPN if Telegram is blocked in your region
• Increase timeout settings in configuration
• The connection retry logic has been improved

5. Addons Directory Issues

Problem: Addons fail to load or directory doesn't exist

Solution:

• The startup script now automatically creates the addons directory
• If cloning fails, it falls back to the local addon files
• Ensure proper permissions: chmod -R 777 addons/

6. Missing Addon Dependencies

Problem: Specific addon features not working

Solution:

• Install missing packages individually:

  pip install jikanpy gingerit google_trans_new covid pyfiglet pyjokes
  pip install markdownify pygments pokedex emoji quotefancy
  pip install lyrics_extractor speech_recognition textblob speedtest shazamio wikipedia
  

Configuration

1. Copy config_template.env to .env
2. Fill in your API credentials and session strings
3. Set up MongoDB connection string
4. Configure log channel ID

Docker Deployment

1. Build the image: docker build -t ultroid .
2. Run with environment variables:

   docker run -d --name ultroid \
     -e SESSION1="your_session_string" \
     -e MONGO_URI="your_mongo_uri" \
     -e API_ID="your_api_id" \
     -e API_HASH="your_api_hash" \
     ultroid
   

Manual Setup

1. Install Python 3.11+
2. Install dependencies: pip install -r requirements.txt
3. Set up environment variables
4. Run: python3 -m pyUltroid

Getting Help

• Check the logs for specific error messages
• Ensure all environment variables are set correctly
• Verify network connectivity to Telegram servers
• Check MongoDB connection if using database features