Skip to main content

Troubleshooting Guide

Common issues and solutions across the ZÈYA platform.

🔍 General Troubleshooting​

API Connection Issues​

Problem: Cannot connect to API

  • Check: API URL in environment variables
  • Check: API server is running
  • Check: Network connectivity
  • Check: CORS configuration on API server
  • Solution: Verify NEXT_PUBLIC_API_URL or EXPO_PUBLIC_API_URL is correct

Problem: 401 Unauthorized errors

  • Check: Token is valid and not expired
  • Check: Token is included in request headers
  • Check: Token format is correct (Bearer {token})
  • Solution: Re-authenticate and get new token

Problem: CORS errors

  • Check: API CORS configuration
  • Check: Request origin is allowed
  • Solution: Update API CORS settings to include your domain

Authentication Issues​

Problem: Login fails

  • Check: Credentials are correct
  • Check: User account is active
  • Check: API endpoint is correct
  • Solution: Verify credentials, check API logs

Problem: Token expires frequently

  • Check: Token TTL configuration
  • Check: Refresh token mechanism
  • Solution: Implement token refresh or increase TTL

Problem: Session lost on app restart

  • Check: Token storage implementation
  • Check: Secure Store/AsyncStorage permissions
  • Solution: Verify token is being saved correctly

🔌 API Backend Issues​

Database Issues​

Problem: Migration fails

  • Check: Database connection settings
  • Check: Database user permissions
  • Check: Migration file syntax
  • Solution: 
    php artisan migrate:fresh
    php artisan migrate:rollback

Problem: Connection refused

  • Check: Database server is running
  • Check: Database credentials in .env
  • Check: Firewall settings
  • Solution: Verify database is accessible

Queue Issues​

Problem: Jobs not processing

  • Check: Queue worker is running
  • Check: Redis connection
  • Check: Queue configuration
  • Solution: 
    php artisan queue:work
    php artisan queue:restart

Problem: Failed jobs accumulating

  • Check: Job error logs
  • Check: Job retry configuration
  • Solution: 
    php artisan queue:failed
    php artisan queue:retry {job-id}

Cache Issues​

Problem: Stale data showing

  • Check: Cache is enabled
  • Check: Cache TTL settings
  • Solution: 
    php artisan cache:clear
    php artisan config:clear
    php artisan route:clear

📱 Mobile App Issues​

Build Issues​

Problem: iOS build fails

  • Check: Xcode is installed
  • Check: CocoaPods dependencies
  • Check: iOS deployment target
  • Solution: 
    cd ios
    pod deintegrate
    pod install
    cd ..

Problem: Android build fails

  • Check: Android SDK is installed
  • Check: Gradle version
  • Check: Build tools version
  • Solution: 
    cd android
    ./gradlew clean
    cd ..

Runtime Issues​

Problem: App crashes on launch

  • Check: Console logs
  • Check: Native dependencies
  • Check: Environment variables
  • Solution: Check Metro bundler logs, verify dependencies

Problem: Images not loading

  • Check: Image URLs are correct
  • Check: Network permissions
  • Check: Image component usage
  • Solution: Use Expo Image component, verify URLs

Problem: Push notifications not working

  • Check: Device token is registered
  • Check: Notification permissions
  • Check: Expo push service configuration
  • Solution: Request permissions, verify token registration

Firebase Issues​

Problem: Firebase not connecting

  • Check: google-services.json exists (Android)
  • Check: GoogleService-Info.plist exists (iOS)
  • Check: Firebase project configuration
  • Solution: Verify Firebase config files are in root directory

🖥️ Admin Panel Issues​

Build Issues​

Problem: Build fails

  • Check: Node.js version
  • Check: Dependencies installed
  • Check: Environment variables
  • Solution: 
    rm -rf .next node_modules
    npm install
    npm run build

Problem: Styles not loading

  • Check: SCSS compilation
  • Check: Bootstrap imports
  • Check: Build output
  • Solution: Verify SCSS files are imported correctly

Runtime Issues​

Problem: Page not found (404)

  • Check: File-based routing
  • Check: File naming convention
  • Check: Route configuration
  • Solution: Verify file exists in pages/ directory

Problem: API calls failing

  • Check: API URL configuration
  • Check: Authentication token
  • Check: CORS settings
  • Solution: Verify API configuration and token

🔧 Common Solutions​

Clear All Caches​

API:

php artisan optimize:clear
php artisan cache:clear
php artisan config:clear
php artisan route:clear
php artisan view:clear

Mobile App:

npx expo start -c
watchman watch-del-all
rm -rf node_modules
npm install

Admin Panel:

rm -rf .next
npm cache clean --force
npm install

Reset Development Environment​

API:

php artisan migrate:fresh --seed
php artisan optimize:clear

Mobile App:

rm -rf node_modules
npm install
cd ios && pod install && cd ..

Admin Panel:

rm -rf .next node_modules
npm install

📞 Getting Help​

If you're still experiencing issues:

  1. Check Logs:

    • API: storage/logs/laravel.log
    • Mobile: Expo CLI console
    • Admin: Browser console and server logs

  2. Search Documentation:

    • Check relevant service documentation
    • Review development guides
    • Check API integration guides

  3. Contact Team:

    • Provide error messages
    • Include relevant logs
    • Describe steps to reproduce