Common errors and resolutions

This section outlines frequent issues encountered during installation, configuration, and operation — along with their causes and how to resolve them.

---

🔑 License & Activation Issues

❌ License Validation Failed

Cause:

• Static IP not used or IP address changed too frequently
• License bound to a different server instance

Resolution:

• Ensure the server uses a static IP
• If license fails or your IP has been greylisted, contact support:
  • via your customer panel, or
  • email: contact@lumeagency.io for reactivation assistance

---

🐳 install.sh / Docker Issues

❌ install.sh Fails on Setup

Common Causes:

• Server already has PHP, MySQL, Docker, NGINX, WHM, etc., pre-installed
• Conflicting services occupying critical ports (80, 3306, 6379)

Resolution:

• Use a clean Ubuntu 22.04 server
• Avoid shared hosting or cPanel servers
• Disable or uninstall any pre-existing services before running install.sh

🔁 Services Not Running After Reboot

Resolution:

docker compose up -d

This will restart all containers as per the docker-compose.yaml.

---

📱 Client App Compilation Issues

❌ Firebase Not Working (Push Not Received)

Cause:

• Firebase not configured properly
• google-services.json (Android) or GoogleService-Info.plist (iOS) missing
• APNs key not uploaded to Firebase for iOS messaging

Resolution:

• Use flutterfire configure or follow Firebase setup wizard
• Ensure platform files are placed in respective directories
• For iOS, upload your APNs authentication key to Firebase under:
  Firebase Console → Project → Messaging → iOS Push Configuration

⚠️ App Crashes or No Splash/Icon

Cause:

• Splash screen or launcher icon not generated

Resolution:

dart run flutter_native_splash:create
dart run flutter_launcher_icons

• Make sure the flutter_native_splash.yaml is configured with proper image paths and colors

---

🗺️ Map Configuration Errors

❌ Map Not Displaying or Blank

Cause:

• Missing or incorrect API keys in .env
• Using a map provider unsupported on a platform (e.g., Google Maps on desktop)

Resolution:

• Double-check .env for MAP_PROVIDER and API key fields
• Adjust per-platform provider in:

static PlatformMapProviderSettings get mapProviderPlatformSettings => ...

• Refer to generic_map pub.dev for compatibility guidelines

---

🛑 Admin Panel Issues

❌ Admin Panel Blank or Crashes on Load

Common Causes:

• .env file missing or incomplete
• Database not reachable
• Redis not started

Resolution:

• Verify .env file is copied and all # REQUIRED fields are filled
• Ensure admin-api is running
• Use docker compose ps to verify container statuses

---

🧠 Database & Redis Errors

❌ Cannot Connect to MySQL (port 3306)

Cause:

• MySQL not running or port conflict

Resolution:

• For Docker: check container with docker logs
• For local: ensure MySQL is installed and running
• Validate connection using: telnet localhost 3306

❌ Redis Connection Fails (port 6379)

Cause:

• Redis not running or blocked by firewall

Resolution:

• Verify Redis status via docker ps or systemctl status redis
• Confirm Redis is exposed on 6379 and no other service is blocking it

---

💡 Quick Debug Checklist

Symptom	Likely Cause	Resolution
License validation fails	IP changed or unlicensed machine	Contact support, ensure static IP
install.sh fails	Pre-installed services on server	Use fresh Ubuntu instance
No push notifications	Firebase misconfigured	Check google-services.json / APNs key
Map doesn’t show	API key/platform mismatch	Check .env, map provider settings
Admin panel won’t load	DB or Redis not up	Check docker services, logs
Wallet or earnings not updating	Backend not syncing or down	Restart services, validate websocket