Troubleshooting

This guide helps you resolve common issues when using Sandroid. Issues are organized by category with step-by-step solutions.

Installation Issues

Legacy Analysis Modules Not Available

Error Message:

Error: Legacy analysis modules not available in this installation!

Root Cause: This error occurred in Sandroid versions before v1.1.0 due to incomplete package migration.

Solution:

Update to latest version:

pip install –upgrade sandroid
Verify installation:

sandroid –version # Should show 1.1.0 or later sandroid –help # Should load without errors
If still failing, reinstall:

pip uninstall sandroid pip install sandroid

Prevention: Always use the latest version from PyPI.

No Module Named ‘src’

Error Message:

ImportError: No module named 'src'

Root Cause: Hardcoded import paths in older versions.

Solution:

Update Sandroid:

pip install –upgrade sandroid>=1.1.0
Clear Python cache:

find . -name “*.pyc” -delete find . -name “__pycache__” -type d -exec rm -rf {} +
Restart Python interpreter if using interactive Python

Missing Dependencies

Error Message:

ModuleNotFoundError: No module named 'frida'

Root Cause: Required dependencies not installed.

Solution:

Install with all dependencies:

pip install sandroid[ai,dev]
For specific missing modules:

pip install frida frida-tools pip install scapy beautifulsoup4
Check requirements:

pip check sandroid

Permission Errors

Error Message:

Permission denied: '/usr/local/bin/sandroid'

Root Cause: Installing without proper permissions.

Solution:

Use user installation:

pip install –user sandroid
Or use virtual environment:

python -m venv venv source venv/bin/activate # Linux/Mac # or: venvScriptsactivate # Windows pip install sandroid
Add to PATH if needed:

export PATH=$PATH:~/.local/bin

Device Connection Issues

ADB Not Found

Error Message:

Android debug bridge path found: None

Root Cause: ADB not installed or not in PATH.

Solution:

Install Android SDK Platform Tools: - Download from https://developer.android.com/studio/releases/platform-tools - Extract and add to PATH
Verify ADB installation:

adb version which adb # Linux/Mac where adb # Windows
Add to PATH permanently:
```
# Linux/Mac (.bashrc or .zshrc)
```
export PATH=$PATH:/path/to/android-sdk/platform-tools

# Windows (System Properties > Environment Variables) Add to PATH: C:pathtoandroid-sdkplatform-tools
Test connection:

adb devices

No Devices Found

Error Message:

List of devices attached
(empty)

Root Cause: No emulator running or USB debugging disabled.

Solution:

Start Android emulator:
```
# List available AVDs
```
emulator -list-avds

# Start emulator emulator -avd Pixel_6_Pro_API_31
For physical devices: - Enable Developer Options - Enable USB Debugging - Accept debugging prompt on device
Check USB connection:

lsusb # Linux # Look for Android device
Restart ADB server:

adb kill-server adb start-server adb devices

Device Unauthorized

Error Message:

List of devices attached
ABC123456 unauthorized

Root Cause: Device hasn’t authorized the computer.

Solution:

Accept authorization prompt on the Android device
If no prompt appears:

adb kill-server adb start-server
Revoke and re-authorize: - Go to Developer Options on device - Revoke USB Debugging authorizations - Reconnect and accept new prompt

Device Not Rooted

Error Message:

[-] none rooted device. Please root it before using FridaAndroidManager

Root Cause: Advanced features require root access.

Solution:

For emulators: Use Google APIs system images (usually rooted)
Verify root access:

adb shell su -c ‘id’
Root emulator if needed: - Use Android Studio AVDs with Google APIs - Or manually root using Magisk/SuperSU
Alternative: Use features that don’t require root:

sandroid –number 2 –screenshot 5 # Basic analysis

Frida Issues

Frida Server Not Running

Error Message:

Frida Server: [Not running]

Root Cause: Frida server not installed or started on device.

Solution:

In interactive mode:

Press ‘f’ to install and start Frida server
Manual installation:
```
# Check device architecture
```
adb shell getprop ro.product.cpu.abi

# Download appropriate frida-server # Install and start via ADB
Verify Frida is working:

frida-ps -U # List processes on USB device
Check Frida server process:

adb shell ps | grep frida

Frida Version Mismatch

Error Message:

Failed to spawn: unable to connect to remote frida-server

Root Cause: Frida client/server version mismatch.

Solution:

Update Frida:

pip install –upgrade frida frida-tools
Reinstall Frida server using Sandroid (interactive mode → ‘f’)
Check versions match:

frida –version adb shell /data/local/tmp/frida-server –version

Frida Connection Timeout

Error Message:

Timeout while connecting to frida-server

Root Cause: Network or device issues.

Solution:

Restart Frida server:

adb shell su -c ‘killall frida-server’ # Then reinstall via Sandroid
Check network connectivity:

adb shell ping 8.8.8.8
Restart ADB connection:

adb kill-server && adb start-server

Analysis Issues

No Results Generated

Symptoms: Analysis completes but no changes detected.

Root Cause: Clean system or insufficient activity.

Solution:

Increase analysis activity: - Install/uninstall apps - Browse internet - Use more features during analysis
Disable noise filtering:

sandroid –avoid-strong-noise-filter
Check baseline is clean: - Use fresh emulator snapshot - Avoid background system updates

Empty or Minimal Output

Symptoms: Very few files or changes reported.

Root Cause: Restrictive noise filtering or limited monitoring scope.

Solution:

Expand monitoring scope:

sandroid –network –sockets –show-deleted
Use multiple runs:

sandroid –number 3
Monitor more file types:

sandroid –avoid-strong-noise-filter

High System Resource Usage

Symptoms: Slow performance, high CPU/memory usage.

Root Cause: Comprehensive monitoring is resource-intensive.

Solution:

Reduce monitoring scope:

sandroid –number 1 –no-processes
Optimize system: - Close unnecessary applications - Use SSD storage for faster I/O - Increase available RAM
Use targeted analysis: - Monitor specific apps only - Shorter screenshot intervals

Analysis Stuck or Hanging

Symptoms: Analysis doesn’t progress or complete.

Root Cause: Device unresponsive or resource exhaustion.

Solution:

Check device responsiveness:

adb shell echo “test”
Monitor system resources:
```
# Linux/Mac
```
htop

# Windows Task Manager
Force restart if needed:
```
# Kill Sandroid processes
```
pkill -f sandroid

# Restart device adb reboot

Network Issues

Network Monitoring Not Working

Symptoms: No network connections captured with --network.

Root Cause: Missing dependencies or permissions.

Solution:

Install network dependencies:

pip install scapy
Check root permissions (required for packet capture)
Verify network activity:

adb shell netstat -an
Test with simple network activity: - Open browser on device - Make HTTP requests

SSL/TLS Interception Failing

Error Message:

friTap hook failed

Root Cause: App uses certificate pinning or advanced protection.

Solution:

Use Objection for bypassing:
```
# In interactive mode: press 'b'
```
objection -g com.app.name explore
Try different hooking methods: - Universal SSL Kill Switch - Custom Frida scripts
Analyze without decryption: - Monitor connection metadata only - Focus on network patterns

Proxy Configuration Issues

Symptoms: Network traffic not routing through proxy.

Root Cause: Incorrect proxy setup or app bypassing proxy.

Solution:

Verify proxy settings:

adb shell settings get global http_proxy
Force proxy for all traffic:
```
# Configure iptables rules if rooted
```
adb shell su -c ‘iptables -t nat -A OUTPUT -p tcp –dport 80 -j REDIRECT –to-port 8080’
Use transparent proxy tools: - mitmproxy in transparent mode - burpsuite with invisible proxying

Configuration Issues

Configuration File Not Found

Error Message:

Configuration file not found: config.toml

Root Cause: File doesn’t exist or wrong path specified.

Solution:

Initialize configuration:

sandroid-config init
Check configuration locations:

sandroid-config paths
Specify full path:

sandroid –config /full/path/to/config.toml
Verify file exists and readable:

ls -la ~/.config/sandroid/sandroid.toml cat ~/.config/sandroid/sandroid.toml

Invalid Configuration Values

Error Message:

ValidationError: Invalid configuration

Root Cause: Configuration contains invalid values or syntax errors.

Solution:

Validate configuration:

sandroid-config validate
Check syntax:
```
# For TOML files
```
python -c “import tomli; tomli.load(open(‘config.toml’, ‘rb’))”
Reset to defaults:

mv ~/.config/sandroid/sandroid.toml ~/.config/sandroid/sandroid.toml.backup sandroid-config init
Check for typos in configuration keys and values

Environment Variable Issues

Symptoms: Environment variables not taking effect.

Root Cause: Incorrect variable names or format.

Solution:

Check variable format:
```
# Correct format
```
export SANDROID_LOG_LEVEL=DEBUG export SANDROID_EMULATOR__DEVICE_NAME=MyDevice

# Incorrect format export sandroid_log_level=debug # Wrong case export SANDROID_EMULATOR.DEVICE_NAME=MyDevice # Wrong separator
Verify variables are set:

env | grep SANDROID
Test variable precedence:

SANDROID_LOG_LEVEL=DEBUG sandroid –loglevel INFO # Environment variable should be overridden by CLI

Memory and Storage Issues

Out of Memory Errors

Error Message:

MemoryError: Unable to allocate memory

Root Cause: Large analysis datasets or memory leaks.

Solution:

Increase system memory or use smaller analysis scope
Clear previous results:

rm -rf results/ rm -f *.json
Use streaming analysis for large datasets
Monitor memory usage:
```
# Linux/Mac
```
free -h

# Check specific process ps aux | grep sandroid

Disk Space Issues

Error Message:

No space left on device

Root Cause: Analysis results consuming too much storage.

Solution:

Clean previous results:

find results/ -type f -mtime +7 -delete # Clean old results
Use custom results path:

sandroid-config set paths.results_path /path/with/more/space
Compress results:

tar -czf results_$(date +%Y%m%d).tar.gz results/ rm -rf results/
Limit screenshot capture:
```
# Reduce screenshot frequency or disable
```
sandroid –screenshot 30 # Every 30 seconds instead of 5

Performance Issues

Slow Analysis Performance

Symptoms: Analysis takes very long to complete.

Root Cause: System limitations or inefficient configuration.

Solution:

Optimize configuration:
```
# Reduce number of runs for testing
```
sandroid –number 1

# Disable resource-intensive features sandroid –no-processes –screenshot 30
System optimization: - Use SSD storage - Close unnecessary applications - Increase virtual memory
Use incremental analysis: - Analyze specific apps instead of full system - Use targeted monitoring

Screenshot Capture Issues

Symptoms: Screenshots not captured or corrupted.

Root Cause: Device screen issues or permissions.

Solution:

Test manual screenshot:

adb shell screencap -p /sdcard/test.png adb pull /sdcard/test.png
Check device screen state: - Ensure screen is on - Disable screen lock - Verify device is responsive
Adjust screenshot interval:
```
# Reduce frequency to avoid overload
```
sandroid –screenshot 10

Getting Help

Log Analysis

Find detailed logs:

# Main log file
tail -f ~/.cache/sandroid/logs/sandroid.log

# Search for specific errors
grep -i "error\|exception\|failed" ~/.cache/sandroid/logs/sandroid.log

Enable debug logging:

SANDROID_LOG_LEVEL=DEBUG sandroid

Save logs for support:

# Copy logs with timestamp
cp ~/.cache/sandroid/logs/sandroid.log sandroid_debug_$(date +%Y%m%d_%H%M%S).log

Reporting Issues

When reporting issues, include:

Sandroid version:

sandroid –version
System information:
```
# Linux/Mac
```
uname -a python –version

# Windows systeminfo | findstr /B /C:”OS Name” /C:”OS Version” python –version
Configuration:

sandroid-config show
Error logs (sanitized of sensitive information)
Steps to reproduce the issue

Report at: https://github.com/fkie-cad/Sandroid_core/issues

Common Solutions Summary

Quick Fixes for Common Issues:

Update Sandroid: pip install --upgrade sandroid
Restart ADB: adb kill-server && adb start-server
Check device connection: adb devices
Validate configuration: sandroid-config validate
Clear Python cache: find . -name "*.pyc" -delete
Enable debug logging: SANDROID_LOG_LEVEL=DEBUG sandroid
Check logs: tail -f ~/.cache/sandroid/logs/sandroid.log

Emergency Reset:

# Complete reset procedure
adb kill-server
pkill -f sandroid
rm -rf ~/.cache/sandroid/
pip uninstall sandroid
pip install sandroid
sandroid-config init
adb start-server
sandroid --version

Prevention Tips

Always use latest version of Sandroid
Test with simple cases before complex analysis
Keep configuration files backed up
Monitor system resources during analysis
Use clean snapshots for baseline analysis
Regular system maintenance (disk cleanup, updates)
Document working configurations for future use

This troubleshooting guide covers the most common issues. For additional help, check the project documentation or create an issue on GitHub with detailed information about your specific problem.