daily-notification-plugin/test-apps/EMULATOR_TROUBLESHOOTING.md

Android Emulator GPU Troubleshooting Guide

Overview

This guide helps resolve GPU binding issues when running Android emulators on Linux systems with NVIDIA graphics cards. The most common issue is when the emulator detects the NVIDIA GPU for Vulkan but still binds OpenGL rendering to the Intel iGPU.

Problem Diagnosis

GPU Binding Issues

Symptoms

• Emulator runs but feels sluggish
• NVIDIA GPU shows low utilization in nvidia-smi
• Emulator banner shows Intel graphics in OpenGL renderer:

  OpenGL Renderer=[Android Emulator OpenGL ES Translator (Mesa Intel(R) Graphics (RPL-S))]
  

• Vulkan detection works but OpenGL compositing uses Intel

Root Cause

The emulator detects your NVIDIA GPU for Vulkan (Selecting Vulkan device: NVIDIA GeForce RTX 4060...) but the window/compositor path still binds to your Intel iGPU. Frames get decoded via gfxstream/Vulkan but final GL presentation rides the Intel driver.

Network Connectivity Issues

Symptoms

• Play Services ANRs and timeouts
• "API failed to connect while resuming" errors
• GmsClientSupervisor ... Timeout... messages
• Phenotype registration failed errors
• NetworkMonitor shows hard failures:
  • ECONNREFUSED on DNS lookups
  • UnknownHostException for www.google.com / connectivitycheck.gstatic.com
  • [100 WIFI] validation failed

Root Cause

The emulator has no working internet/DNS connectivity, causing Google apps to stall and ANR. This is often caused by:

• DNS resolution failures
• VPN/killswitch blocking emulator traffic
• Firewall rules blocking outbound connections
• Corrupted network state from previous sessions

Solution Strategies

1. Network Connectivity Fixes (Priority)

If experiencing ANRs and Play Services failures, address network issues first:

Quick Network Fix

cd test-apps
./launch-emulator-network-fix.sh

Verify Network Status

cd test-apps
./verify-emulator-network.sh

Manual Network Verification

# Check airplane mode
adb -e shell settings get global airplane_mode_on

# Check network interfaces
adb -e shell ip addr; adb -e shell ip route

# Test DNS resolution
adb -e shell ping -c1 8.8.8.8
adb -e shell ping -c1 connectivitycheck.gstatic.com

Clear Play Services Cache

adb -e shell pm clear com.google.android.gms
adb -e shell pm clear com.android.vending

2. GPU Binding Solutions

Use the enhanced launch script with all NVIDIA offloading variables:

cd test-apps
./launch-emulator-gpu.sh

What each variable does:

• __NV_PRIME_RENDER_OFFLOAD=1 + __GLX_VENDOR_LIBRARY_NAME=nvidia: Offload GL to NVIDIA
• __VK_LAYER_NV_optimus=NVIDIA_only + VK_ICD_FILENAMES=...nvidia_icd.json: Make Vulkan loader pick NVIDIA
• DRI_PRIME=1: Belt-and-suspenders in mixed Mesa/NVIDIA setups
• QT_QPA_PLATFORM=xcb: Avoids Wayland/Qt oddities
• -no-snapshot-load: Prevents flaky snapshots from different configs

2. Alternative GPU Modes

If the primary solution still binds to Intel, try these alternatives:

Pure OpenGL Mode

cd test-apps
./launch-emulator-opengl.sh

• Removes -feature Vulkan to avoid mixed VK+GL path
• Forces pure OpenGL rendering on NVIDIA
• Good when Vulkan+OpenGL mixed mode causes issues

ANGLE Mode

cd test-apps
./launch-emulator-angle.sh

• Uses ANGLE (Almost Native Graphics Layer Engine)
• Better NVIDIA compatibility on Linux
• More stable rendering pipeline

Mesa Fallback

cd test-apps
./launch-emulator-mesa.sh

• Software rendering as last resort
• Use only for stability testing
• More CPU intensive but very stable

3. Manual Launch Commands

If scripts don't work, use these manual commands:

Enhanced GPU Launch

QT_QPA_PLATFORM=xcb \
__NV_PRIME_RENDER_OFFLOAD=1 \
__GLX_VENDOR_LIBRARY_NAME=nvidia \
__VK_LAYER_NV_optimus=NVIDIA_only \
VK_ICD_FILENAMES=/usr/share/vulkan/icd.d/nvidia_icd.json \
DRI_PRIME=1 \
emulator -avd TimeSafari_Emulator \
  -gpu host \
  -feature Vulkan \
  -accel on \
  -no-boot-anim \
  -no-snapshot-load

Pure OpenGL

QT_QPA_PLATFORM=xcb \
__NV_PRIME_RENDER_OFFLOAD=1 \
__GLX_VENDOR_LIBRARY_NAME=nvidia \
DRI_PRIME=1 \
emulator -avd TimeSafari_Emulator \
  -gpu host \
  -accel on \
  -no-boot-anim

ANGLE Mode

QT_QPA_PLATFORM=xcb \
__NV_PRIME_RENDER_OFFLOAD=1 \
__GLX_VENDOR_LIBRARY_NAME=nvidia \
DRI_PRIME=1 \
emulator -avd TimeSafari_Emulator \
  -gpu angle_indirect \
  -accel on \
  -no-boot-anim

Verification

Check GPU Binding

After launching, check the emulator banner for:

• ✅ Good: OpenGL Vendor=Google (NVIDIA) or GL translator running atop NVIDIA
• ❌ Bad: (Mesa Intel) or Intel graphics in renderer

Monitor GPU Usage

# Real-time GPU utilization
nvidia-smi dmon -s u

# Check emulator process specifically
watch -n1 "nvidia-smi --query-compute-apps=pid,process_name,used_memory --format=csv,noheader | grep qemu"

You should see non-zero GPU utilization/memory for the emulator process.

Additional Optimizations

Clean Snapshots

Snapshots made with different configs can cause issues:

# Delete snapshots for clean state
rm -rf ~/.android/avd/TimeSafari_Emulator.avd/snapshots/

Fix ADB Issues

"Device offline" after boot is common with snapshots:

adb kill-server && adb start-server
adb -e wait-for-device

Disable Unnecessary Features

Save CPU, reduce log spam, and prevent hangs:

emulator -avd TimeSafari_Emulator \
  -gpu host -accel on -no-boot-anim \
  -feature -Bluetooth -camera-back none -camera-front none -no-audio

Key Benefits:

• -feature -Bluetooth: Prevents Bluetooth-related hangs and ANRs
• -camera-back none -camera-front none: Disables camera hardware
• -no-audio: Disables audio system (saves resources)

CPU/RAM Configuration

Keep your existing settings:

emulator -avd TimeSafari_Emulator \
  -cores 6 -memory 4096 \
  -gpu host -accel on -no-boot-anim

Troubleshooting Checklist

Before Launch

• NVIDIA drivers installed and working
• Vulkan ICD file exists: /usr/share/vulkan/icd.d/nvidia_icd.json
• AVD exists and is properly configured
• Android SDK and emulator in PATH

After Launch

• Check emulator banner for correct GPU binding
• Monitor nvidia-smi for GPU utilization
• Verify ADB connection with adb devices
• Test app installation and functionality

If Still Having Issues

• Try different GPU modes (OpenGL, ANGLE, Mesa)
• Clean snapshots and restart
• Check system logs for GPU errors
• Verify NVIDIA driver compatibility
• Consider software rendering for stability testing

Performance Expectations

Hardware Acceleration (NVIDIA)

• GPU Utilization: 20-60% during normal use
• Memory Usage: 500MB-2GB GPU memory
• UI Responsiveness: Smooth, 60fps target
• Startup Time: 30-60 seconds

Software Rendering (Mesa)

• CPU Usage: 50-80% on all cores
• Memory Usage: 1-4GB system RAM
• UI Responsiveness: Slower, 30fps typical
• Startup Time: 60-120 seconds

System Requirements

Minimum

• CPU: 4 cores, 2.5GHz+
• RAM: 8GB system, 4GB for emulator
• GPU: Any with OpenGL 3.0+ support
• Storage: 10GB free space

Recommended

• CPU: 6+ cores, 3.0GHz+
• RAM: 16GB system, 6GB for emulator
• GPU: NVIDIA GTX 1060+ or equivalent
• Storage: 20GB free space, SSD preferred

Support

If you continue experiencing issues:

1. Check the Android Emulator documentation
2. Review NVIDIA Linux driver documentation
3. Test with different AVD configurations
4. Consider using physical Android devices for testing