Troubleshooting

This guide helps you resolve common issues when using Rhamaa CLI. If you don't find your issue here, please check our FAQ or create an issue on GitHub.

Installation Issues

Command Not Found

Problem: rhamaa: command not found after installation

Solutions:

1. Check Installation Path

   pip show rhamaa
   # Check if the installation directory is in your PATH
   

2. Use Python Module

   python -m rhamaa --help
   

3. Install with User Flag

   pip install --user rhamaa
   

4. Check Virtual Environment

   which python
   which pip
   # Ensure you're in the correct environment
   

Permission Errors

Problem: Permission denied during installation

Solutions:

1. Use User Installation

   pip install --user rhamaa
   

2. Use Virtual Environment

   python -m venv rhamaa-env
   source rhamaa-env/bin/activate  # Linux/Mac
   pip install rhamaa
   

3. Fix Permissions (Linux/Mac)

   sudo chown -R $USER:$USER ~/.local
   

Python Version Issues

Problem: Rhamaa CLI requires Python 3.7+

Solutions:

1. Check Python Version

   python --version
   python3 --version
   

2. Use Specific Python Version

   python3.8 -m pip install rhamaa
   python3.8 -m rhamaa --help
   

3. Update Python

4. Install Python 3.7+ from python.org
5. Use pyenv for version management

Project Creation Issues

Wagtail Not Found

Problem: wagtail: command not found when running rhamaa start

Solutions:

1. Install Wagtail

   pip install wagtail
   

2. Check Wagtail Installation

   wagtail --version
   

3. Use Same Environment

   # Ensure Wagtail and Rhamaa are in the same environment
   pip list | grep wagtail
   pip list | grep rhamaa
   

Template Download Fails

Problem: Template download fails or times out

Solutions:

1. Check Internet Connection

   ping github.com
   

2. Check GitHub Access

   curl -I https://github.com/RhamaaCMS/RhamaaCMS
   

3. Use VPN/Proxy

4. If behind corporate firewall

5. Configure proxy settings

6. Manual Download

   # Download template manually
   wget https://github.com/RhamaaCMS/RhamaaCMS/archive/refs/heads/main.zip
   wagtail start --template=main.zip MyProject
   

Project Already Exists

Problem: Directory with project name already exists

Solutions:

1. Choose Different Name

   rhamaa start MyProject2
   

2. Remove Existing Directory

   rm -rf MyProject
   rhamaa start MyProject
   

3. Backup Existing

   mv MyProject MyProject_backup
   rhamaa start MyProject
   

App Installation Issues

Not a Wagtail Project

Problem: "This doesn't appear to be a Wagtail project"

Solutions:

1. Check Current Directory

   ls -la
   # Look for manage.py or Django project files
   

2. Navigate to Project Root

   cd /path/to/your/wagtail/project
   rhamaa startapp iot --prebuild mqtt
   

3. Verify Project Structure

   # Should have manage.py and Django structure
   python manage.py --version
   

App Not Found

Problem: "App 'appname' not found in registry"

Solutions:

1. Check Available Apps

   rhamaa startapp --list
   

2. Check Spelling

   # Correct: mqtt, users, articles, lms
   # Example install key usage is on the left; use exact lowercase keys
   

3. Get App Information

   rhamaa startapp --list
   

App Already Exists

Problem: "App already exists in apps/ directory"

Solutions:

1. Use Force Flag

   rhamaa startapp iot --prebuild mqtt --force
   

2. Remove Existing App

   rm -rf apps/mqtt
   rhamaa add mqtt
   

3. Backup Existing

   mv apps/mqtt apps/mqtt_backup
   rhamaa add mqtt
   

Download Failures

Problem: App download fails or is corrupted

Solutions:

1. Check Internet Connection

   ping github.com
   curl -I https://github.com/RhamaaCMS/mqtt-apps
   

2. Clear Temporary Files

   # Clear system temp directory
   rm -rf /tmp/rhamaa_*  # Linux/Mac
   

3. Retry Installation

   rhamaa add mqtt --force
   

4. Manual Installation

   # Download manually
   git clone https://github.com/RhamaaCMS/mqtt-apps.git apps/mqtt
   

Runtime Issues

Import Errors

Problem: ImportError when running Django

Solutions:

1. Check INSTALLED_APPS

   # settings.py
   INSTALLED_APPS = [
       # ... other apps
       'apps.mqtt',  # Correct path
   ]
   

2. Run Migrations

   python manage.py makemigrations
   python manage.py migrate
   

3. Check App Structure

   ls -la apps/mqtt/
   # Should have __init__.py and other Django files
   

Migration Issues

Problem: Migration errors after installing apps

Solutions:

1. Check Dependencies

   pip install -r requirements.txt
   

2. Reset Migrations

   # Remove migration files (be careful!)
   rm apps/mqtt/migrations/0*.py
   python manage.py makemigrations mqtt
   python manage.py migrate
   

3. Fake Migrations

   python manage.py migrate --fake-initial
   

Static Files Issues

Problem: Static files not loading

Solutions:

1. Collect Static Files

   python manage.py collectstatic
   

2. Check Static Settings

   # settings.py
   STATIC_URL = '/static/'
   STATIC_ROOT = os.path.join(BASE_DIR, 'staticfiles')
   

3. Check App Static Directory

   ls -la apps/mqtt/static/
   

Network Issues

Corporate Firewalls

Problem: Downloads fail behind corporate firewall

Solutions:

1. Configure Proxy

   export HTTP_PROXY=http://proxy.company.com:8080
   export HTTPS_PROXY=http://proxy.company.com:8080
   

2. Use pip Proxy

   pip install --proxy http://proxy.company.com:8080 rhamaa
   

3. Download Manually

   # Download ZIP files manually and extract
   

DNS Issues

Problem: Cannot resolve GitHub domains

Solutions:

1. Check DNS

   nslookup github.com
   

2. Use Different DNS

   # Use Google DNS
   echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf
   

3. Use IP Address

   # Add to /etc/hosts
   140.82.112.3 github.com
   

Performance Issues

Slow Downloads

Problem: App downloads are very slow

Solutions:

1. Check Connection Speed

   speedtest-cli
   

2. Use Different Network

3. Try different WiFi network

4. Use mobile hotspot

5. Download During Off-Peak

6. Try downloading at different times

Memory Issues

Problem: Out of memory during installation

Solutions:

1. Close Other Applications

2. Free up system memory

3. Increase Swap Space (Linux)

   sudo fallocate -l 2G /swapfile
   sudo chmod 600 /swapfile
   sudo mkswap /swapfile
   sudo swapon /swapfile
   

4. Use Smaller Apps

5. Install apps one at a time

Environment Issues

Virtual Environment Problems

Problem: Apps not working in virtual environment

Solutions:

1. Activate Environment

   source .venv/bin/activate  # Linux/Mac
   .venv\Scripts\activate     # Windows
   

2. Check Environment

   which python
   which pip
   pip list
   

3. Recreate Environment

   deactivate
   rm -rf .venv
   python -m venv .venv
   source .venv/bin/activate
   pip install rhamaa wagtail
   

Path Issues

Problem: Python can't find installed packages

Solutions:

1. Check Python Path

   import sys
   print(sys.path)
   

2. Install in Development Mode

   pip install -e .
   

3. Add to Python Path

   export PYTHONPATH="${PYTHONPATH}:/path/to/your/project"
   

Getting More Help

Debug Information

When reporting issues, include:

# System information
python --version
pip --version
rhamaa --version  # or python -m rhamaa --version

# Environment information
pip list | grep -E "(rhamaa|wagtail|django)"

# Error messages
   # For detailed steps, re-run with --force and capture full output
   rhamaa startapp iot --prebuild mqtt --force

Log Files

Check for log files in:

• /tmp/rhamaa.log (Linux/Mac)
• %TEMP%\rhamaa.log (Windows)
• Current directory

Reporting Issues

When creating GitHub issues:

1. Use Issue Template: Follow the provided template
2. Include Debug Info: System and environment details
3. Provide Steps: How to reproduce the issue
4. Include Logs: Error messages and log files
5. Be Specific: Exact commands and error messages

Community Support

• GitHub Issues: https://github.com/RhamaaCMS/RhamaaCLI/issues
• Discussions: https://github.com/RhamaaCMS/RhamaaCLI/discussions
• Documentation: Check this documentation thoroughly

Prevention Tips

Best Practices

1. Use Virtual Environments: Always use virtual environments
2. Keep Updated: Update Rhamaa CLI regularly
3. Check Requirements: Verify system requirements
4. Backup Projects: Backup before major changes
5. Test First: Test in development environment

Regular Maintenance

# Update Rhamaa CLI
pip install --upgrade rhamaa

# Check for issues
   rhamaa --help
   rhamaa startapp --list

# Clean temporary files
rm -rf /tmp/rhamaa_*

If you continue to experience issues after trying these solutions, please create an issue on our GitHub repository with detailed information about your problem.