Skip to main content

​
Installation Issues

​
APK Installation Failed

Symptoms: Installation fails with “App not installed” message.Solutions:
  • Enable “Install from Unknown Sources” in Android settings
  • Check that you have sufficient storage space (at least 100MB free)
  • Uninstall any previous version of PhoneClaw before installing
  • Verify the APK file downloaded completely and isn’t corrupted
  • Try installing via ADB: adb install phoneclaw.apk
Symptoms: “There was a problem parsing the package” error.Solutions:
  • Ensure your Android version is 7.0 (API 24) or higher
  • Re-download the APK file as it may be corrupted
  • Check that your device architecture is supported (ARM/ARM64)
  • Build the APK directly from source if downloaded version fails

​
Build Errors

Symptoms: Android Studio fails to sync Gradle dependencies.Solutions:
  • Update Android Studio to the latest version
  • Check your internet connection for downloading dependencies
  • Clear Gradle cache: File > Invalidate Caches / Restart
  • Delete .gradle folder in project root and sync again
  • Verify JDK version is 11 or higher in File > Project Structure
Symptoms: Build fails with “MOONDREAM_AUTH not found” error.Solutions: Create local.properties file in project root with:
MOONDREAM_AUTH=YOUR_TOKEN_HERE
  • Never commit API keys to version control
  • Obtain your Moondream token from your account dashboard
  • Restart Android Studio after adding the key

​
Permission Issues

​
Accessibility Service Not Working

Symptoms: Scripts run but don’t interact with UI elements.Solutions:
  1. Open Android Settings > Accessibility
  2. Find PhoneClaw in the list
  3. Toggle the accessibility service ON
  4. Grant the permission when prompted
  5. Return to PhoneClaw and try again
Note: Some devices hide accessibility settings. Search for “accessibility” in Settings search.
Symptoms: Accessibility service permission disables automatically.Solutions:
  • Disable battery optimization for PhoneClaw:
    • Settings > Battery > Battery Optimization
    • Find PhoneClaw and select Don’t optimize
  • Add PhoneClaw to protected apps list (MIUI, EMUI, ColorOS)
  • Disable “Remove permissions if app is unused” for PhoneClaw
  • Check manufacturer-specific app settings for background restrictions

​
Microphone/Voice Command Issues

Symptoms: App doesn’t respond to voice input.Solutions:
  • Grant microphone permission in Android settings
  • Check that device microphone is working in other apps
  • Speak clearly and close to the device
  • Ensure no other app is using the microphone
  • Try restarting PhoneClaw after granting permissions

​
Automation Issues

​
magicClicker Not Finding Elements

Symptoms: magicClicker() fails to find or tap UI elements.Solutions:
  • Use more specific, descriptive element names
  • Add delays before magicClicker to allow UI to load: 
    await delay(2000);
await magicClicker("Submit button");
  • Check that element is visible on screen (not scrolled off)
  • Verify accessibility service permission is enabled
  • Try different descriptions (e.g., “blue submit button” instead of “submit”)
  • Some apps block accessibility interactions - test with different apps
Symptoms: magicClicker taps the wrong UI element.Solutions:
  • Be more specific in your description: 
    // Instead of:
magicClicker("button");

// Use:
magicClicker("blue login button at the bottom");
  • Scroll to make target element more prominent
  • Use position hints (“top”, “bottom”, “left”, “right”)
  • Verify element descriptions match visible text or labels

​
magicScraper Not Returning Data

Symptoms: magicScraper() returns null or wrong information.Solutions:
  • Ensure text is clearly visible on screen
  • Add delay before scraping to allow content to load: 
    await delay(1500);
const code = await magicScraper("The 6-digit verification code");
  • Make questions specific and focused on visible content
  • Verify the text you’re looking for is actually displayed
  • Some fonts or colors may be harder for vision to read
  • Take a screenshot to verify what’s visible to the scraper

​
Scheduling Problems

Symptoms: Cron-scheduled automations don’t execute at expected times.Solutions:
  • Verify cron expression is valid: Cron Expression Validator
  • Disable battery optimization for PhoneClaw
  • Check that accessibility service is enabled
  • Ensure device isn’t in deep sleep mode during scheduled time
  • Add PhoneClaw to protected apps (manufacturer-specific)
  • Review scheduled tasks in PhoneClaw settings
  • Try a simpler schedule first (e.g., every 5 minutes) to test
Symptoms: Scheduled tasks continue running after clearSchedule().Solutions:
  • Restart PhoneClaw app after calling clearSchedule()
  • Check for multiple script instances that might be scheduling
  • Manually clear schedules from PhoneClaw settings
  • Verify clearSchedule() is actually being called in your script

​
Performance Issues

​
Slow Automation Execution

Symptoms: Automations take much longer than expected.Solutions:
  • Reduce delay durations where possible (but keep enough for UI loading)
  • Use more specific magicClicker descriptions to reduce search time
  • Close unnecessary background apps to free resources
  • Restart device if it’s been running for extended periods
  • Consider device limitations (older/budget phones are slower)
  • Break complex automations into smaller, focused scripts

​
App Crashes or Freezes

Symptoms: App closes unexpectedly or becomes unresponsive.Solutions:
  • Update to latest version of PhoneClaw
  • Clear app cache: Settings > Apps > PhoneClaw > Clear Cache
  • Check device has sufficient free RAM (at least 500MB)
  • Avoid running too many simultaneous automations
  • Add error handling in scripts: 
    try {
  await magicClicker("Button");
} catch (error) {
  speakText("Error: " + error);
}
  • Report persistent crashes on GitHub with device info and logs

​
Device-Specific Issues

​
MIUI (Xiaomi) Devices

MIUI has aggressive battery optimization that can interfere with PhoneClaw.
Required settings:
  1. Settings > Battery & Performance > App battery saver > PhoneClaw > No restrictions
  2. Settings > Apps > Manage apps > PhoneClaw > Autostart > Enable
  3. Security > Permissions > Autostart > Enable for PhoneClaw

​
Samsung Devices

Required settings:
  1. Settings > Battery > Background usage limits > Remove PhoneClaw
  2. Settings > Apps > PhoneClaw > Battery > Optimize battery usage > Off

​
Huawei (EMUI) Devices

Required settings:
  1. Settings > Battery > App launch > PhoneClaw > Manage manually
  2. Enable all three toggles (Auto-launch, Secondary launch, Run in background)

​
Getting More Help

If your issue isn’t listed here:

Check FAQ

Review frequently asked questions for additional help

Debugging Guide

Learn how to debug automation scripts

Discord Support

Get help from the community

GitHub Issues

Report bugs or request features