> ## Documentation Index
> Fetch the complete documentation index at: https://www.minitap.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common issues and solutions

This guide helps you diagnose and resolve common issues when working with the Mobile Use SDK.

## Device Connection Issues

### No Device Found

<AccordionGroup>
  <Accordion title="Symptoms" icon="triangle-exclamation">
    * Error: `DeviceNotFoundError: No device found. Exiting.`
    * Agent initialization fails
  </Accordion>

  <Accordion title="Solutions" icon="check">
    **1. Verify device connection**

    <Tabs>
      <Tab title="Android">
        ```bash theme={null}
        adb devices
        ```

        You should see your device listed with status "device"
      </Tab>

      <Tab title="iOS">
        ```bash theme={null}
        idevice_id -l
        ```
      </Tab>
    </Tabs>

    **2. Enable USB debugging (Android)**

    * Settings → About Phone → Tap "Build Number" 7 times
    * Settings → Developer options → USB debugging

    **3. Trust computer (iOS)**

    * Unlock your device
    * Tap "Trust" when prompted

    **4. Reset ADB**

    ```bash theme={null}
    adb kill-server
    adb start-server
    ```

    **5. Specify device manually**

    ```python theme={null}
    from minitap.mobile_use.sdk.builders import Builders
    from minitap.mobile_use.sdk.types import DevicePlatform

    config = (
        Builders.AgentConfig
        .for_device(platform=DevicePlatform.ANDROID, device_id="your_device_id")
        .build()
    )
    agent = Agent(config=config)
    ```
  </Accordion>
</AccordionGroup>

***

### USB Connection Unstable

<AccordionGroup>
  <Accordion title="Symptoms" icon="triangle-exclamation">
    * Random disconnections during automation
    * `adb: error: device 'xxx' not found`
  </Accordion>

  <Accordion title="Solutions" icon="check">
    **1. Use a high-quality USB cable**

    Poor quality cables can cause intermittent connections.

    **2. Connect directly to computer**

    Avoid USB hubs which can cause instability.

    **3. Increase ADB timeout**

    ```bash theme={null}
    adb shell settings put global adb_timeout 0
    ```

    **4. Use wireless debugging**

    ```bash theme={null}
    # Enable TCP/IP mode
    adb tcpip 5555

    # Connect wirelessly
    adb connect <device_ip>:5555
    ```

    <Warning>
      Ensure stable Wi-Fi connection for wireless debugging.
    </Warning>
  </Accordion>
</AccordionGroup>

***

## Server-Related Issues

### Servers Fail to Start

<AccordionGroup>
  <Accordion title="Symptoms" icon="triangle-exclamation">
    * `ServerStartupError` during initialization
    * Ports already in use
    * Zombie processes from previous runs
  </Accordion>

  <Accordion title="Solutions" icon="check">
    **1. Force clean zombie servers**

    ```python theme={null}
    agent = Agent()

    # Kill any existing mobile-use servers
    agent.clean(force=True)

    # Now initialize
    agent.init()
    ```

    **2. Verify platform tools are installed**

    <Tabs>
      <Tab title="Android">
        ```bash theme={null}
        adb version
        ```

        If not installed, download [Android SDK Platform Tools](https://developer.android.com/tools/adb)
      </Tab>

      <Tab title="iOS">
        ```bash theme={null}
        idb --help
        ```

        If not installed, install via: `brew install idb-companion`
      </Tab>
    </Tabs>

    **3. Check idb\_companion status (iOS)**

    ```bash theme={null}
    # Check if idb_companion is running
    pgrep -l idb_companion

    # Start idb_companion if needed
    idb_companion --udid booted
    ```

    **4. Check for port conflicts**

    ```bash theme={null}
    # Linux/Mac
    lsof -i :8000
    lsof -i :8001

    # Windows
    netstat -ano | findstr :8000
    netstat -ano | findstr :8001
    ```
  </Accordion>
</AccordionGroup>

***

## Task Execution Issues

### Agent Not Initialized

<AccordionGroup>
  <Accordion title="Symptoms" icon="triangle-exclamation">
    * Error: `AgentNotInitializedError`
  </Accordion>

  <Accordion title="Solution" icon="check">
    Always call `agent.init()` before running tasks:

    ```python theme={null}
    agent = Agent()

    # Initialize first!
    if not agent.init():
        print("Initialization failed")
        exit(1)

    # Now you can run tasks
    await agent.run_task(goal="Your task")
    ```
  </Accordion>
</AccordionGroup>

***

### Task Times Out or Fails

<AccordionGroup>
  <Accordion title="Symptoms" icon="triangle-exclamation">
    * Task gets stuck or fails to complete
    * Reaches max\_steps limit
    * Unexpected results
  </Accordion>

  <Accordion title="Solutions" icon="check">
    **1. Simplify the task goal**

    Break complex tasks into smaller steps:

    ```python theme={null}
    # ❌ Too complex
    await agent.run_task(
        goal="Open settings, go to network, enable airplane mode, "
             "wait 5 seconds, then disable airplane mode"
    )

    # ✅ Break into steps
    await agent.run_task(goal="Open settings and go to network settings")
    await agent.run_task(goal="Enable airplane mode")
    await asyncio.sleep(5)
    await agent.run_task(goal="Disable airplane mode")
    ```

    **2. Increase max\_steps limit**

    ```python theme={null}
    task = (
        agent.new_task("Complex goal...")
        .with_max_steps(500)  # Default is 400
        .build()
    )

    await agent.run_task(request=task)
    ```

    **3. Enable tracing to debug**

    ```python theme={null}
    task = (
        agent.new_task("Your goal")
        .with_trace_recording(enabled=True)
        .build()
    )

    await agent.run_task(request=task)
    # Check traces in mobile-use-traces/ directory
    ```

    **4. Be more specific in goals**

    ```python theme={null}
    # ❌ Vague
    goal = "Check the weather"

    # ✅ Specific
    goal = "Open the Weather app, check the current temperature in Celsius for New York, and tell me tomorrow's forecast"
    ```
  </Accordion>
</AccordionGroup>

***

### Incorrect Task Results

<AccordionGroup>
  <Accordion title="Symptoms" icon="triangle-exclamation">
    * Task returns unexpected or incomplete data
    * Structured output fields are missing or incorrect
  </Accordion>

  <Accordion title="Solutions" icon="check">
    **1. Use structured output with clear descriptions**

    ```python theme={null}
    from pydantic import BaseModel, Field

    class WeatherInfo(BaseModel):
        current_temp: float = Field(
            ..., 
            description="Current temperature in Celsius"
        )
        condition: str = Field(
            ..., 
            description="Current weather condition (sunny, cloudy, rainy, etc.)"
        )
        tomorrow_forecast: str = Field(
            ..., 
            description="Detailed weather forecast for tomorrow"
        )

    result = await agent.run_task(
        goal="Check weather for today and tomorrow",
        output=WeatherInfo
    )
    ```

    **2. Provide more context in the goal**

    ```python theme={null}
    # ❌ Unclear
    goal = "Get product info"

    # ✅ Clear
    goal = "Go to Amazon, search for 'wireless headphones', open the first result, and get the product name, price, and rating"
    ```

    **3. Use better LLM models for cortex**

    ```python theme={null}
    from minitap.mobile_use.config import LLM, LLMConfig, LLMWithFallback

    profile = AgentProfile(
        name="accurate",
        llm_config=LLMConfig(
            cortex=LLMWithFallback(
                provider="openai",
                model="o4-mini",  # More powerful model
                fallback=LLM(provider="openai", model="gpt-5")
            ),
            # ... other components
        )
    )
    ```
  </Accordion>
</AccordionGroup>

***

## LLM and API Issues

### API Key Authentication

<AccordionGroup>
  <Accordion title="Symptoms" icon="triangle-exclamation">
    * Authentication errors
    * `openai.error.AuthenticationError` or similar
    * 401 Unauthorized responses
  </Accordion>

  <Accordion title="Solutions" icon="check">
    **1. Verify API keys in .env file**

    ```bash .env theme={null}
    # Required based on your LLM config
    OPENAI_API_KEY=sk-...
    XAI_API_KEY=xai-...
    OPEN_ROUTER_API_KEY=sk-or-...
    GOOGLE_API_KEY=...
    ```

    **2. Load environment variables**

    The SDK automatically loads `.env` files, but you can also set manually:

    ```python theme={null}
    import os
    from dotenv import load_dotenv

    load_dotenv()  # Explicit load

    # Or set programmatically
    os.environ["OPENAI_API_KEY"] = "your_key"
    ```

    **3. Check API key validity**

    Test your keys directly:

    ```python theme={null}
    from openai import OpenAI

    client = OpenAI(api_key=os.getenv("OPENAI_API_KEY"))
    response = client.chat.completions.create(
        model="gpt-5-nano",
        messages=[{"role": "user", "content": "test"}]
    )
    print("API key works!")
    ```
  </Accordion>
</AccordionGroup>

***

### Rate Limiting

<AccordionGroup>
  <Accordion title="Symptoms" icon="triangle-exclamation">
    * 429 Too Many Requests errors
    * Tasks slow down over time
  </Accordion>

  <Accordion title="Solutions" icon="check">
    **1. Use different providers**

    Distribute load across multiple LLM providers:

    ```python theme={null}
    llm_config = LLMConfig(
        planner=LLM(provider="openai", model="gpt-5-nano"),
        cortex=LLM(provider="google", model="gemini-2.5-flash"),
        executor=LLM(provider="openrouter", model="meta-llama/llama-4-scout")
    )
    ```

    **2. Use tier limits**

    Check your API tier limits and upgrade if needed.

    **3. Add delays between tasks**

    ```python theme={null}
    import asyncio

    for task_goal in task_list:
        await agent.run_task(goal=task_goal)
        await asyncio.sleep(2)  # Brief delay
    ```
  </Accordion>
</AccordionGroup>

***

## System Environment Issues

### Python Version Compatibility

<AccordionGroup>
  <Accordion title="Symptoms" icon="triangle-exclamation">
    * Import errors or syntax errors
    * `SyntaxError` or `ModuleNotFoundError`
  </Accordion>

  <Accordion title="Solution" icon="check">
    Ensure you're using Python 3.12 or higher:

    ```bash theme={null}
    python --version
    # Should be 3.12.x or higher
    ```

    **Create compatible environment:**

    <Tabs>
      <Tab title="UV (Recommended)">
        ```bash theme={null}
        # UV handles Python versions automatically
        curl -LsSf https://astral.sh/uv/install.sh | sh

        uv venv --python 3.12
        source .venv/bin/activate
        uv add minitap-mobile-use
        ```
      </Tab>

      <Tab title="venv">
        ```bash theme={null}
        python3.12 -m venv venv
        source venv/bin/activate  # Windows: venv\Scripts\activate
        pip install minitap-mobile-use
        ```
      </Tab>
    </Tabs>
  </Accordion>
</AccordionGroup>

***

### Import Errors

<AccordionGroup>
  <Accordion title="Symptoms" icon="triangle-exclamation">
    * `ModuleNotFoundError: No module named 'minitap'`
    * Import errors for SDK components
  </Accordion>

  <Accordion title="Solutions" icon="check">
    **1. Verify installation**

    ```bash theme={null}
    pip list | grep minitap
    # Should show: minitap-mobile-use
    ```

    **2. Reinstall the SDK**

    ```bash theme={null}
    pip uninstall minitap-mobile-use
    pip install minitap-mobile-use
    ```

    **3. Check virtual environment**

    Ensure you're in the correct virtual environment:

    ```bash theme={null}
    which python
    # Should point to your venv
    ```
  </Accordion>
</AccordionGroup>

***

## Debugging Best Practices

### Enable Comprehensive Logging

```python theme={null}
import logging

# Enable debug logging
logging.basicConfig(level=logging.DEBUG)

# Or for mobile-use specifically
from minitap.mobile_use.utils.logger import get_logger

logger = get_logger(__name__)
logger.setLevel(logging.DEBUG)
```

### Use Trace Recording

Always enable tracing during development:

```python theme={null}
from pathlib import Path
from datetime import datetime

timestamp = datetime.now().strftime("%Y%m%d_%H%M%S")
trace_path = Path(f"/tmp/debug_traces/{timestamp}")

task = (
    agent.new_task("Your goal")
    .with_trace_recording(enabled=True, path=trace_path)
    .with_thoughts_output_saving(path=f"{trace_path}/thoughts.txt")
    .with_llm_output_saving(path=f"{trace_path}/output.json")
    .build()
)
```

### Check Trace Contents

After a failed task, examine the traces:

```bash theme={null}
ls /tmp/debug_traces/20241009_175416/

# View screenshots to see what the agent saw
# Read thoughts.txt to understand agent reasoning
# Check output.json for structured results
```

***

## Getting Help

<CardGroup cols={2}>
  <Card title="GitHub Issues" icon="github" href="https://github.com/minitap-ai/mobile-use/issues">
    Search existing issues or create a new one
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/6nSqmQ9pQs">
    Get help from the community
  </Card>
</CardGroup>

### Filing a Bug Report

When filing an issue, include:

<Steps>
  <Step title="Environment Information">
    ```bash theme={null}
    # Python version
    python --version

    # SDK version
    pip show minitap-mobile-use

    # OS
    uname -a  # Linux/Mac
    # or
    systeminfo  # Windows
    ```
  </Step>

  <Step title="Device Details">
    * Platform (Android/iOS)
    * Device model
    * OS version
  </Step>

  <Step title="Minimal Reproduction">
    Provide a minimal code sample that reproduces the issue
  </Step>

  <Step title="Error Messages">
    Full error traceback and logs
  </Step>

  <Step title="Traces (if applicable)">
    Include relevant screenshots from trace recording
  </Step>
</Steps>

***

## Quick Reference

<AccordionGroup>
  <Accordion title="Clean zombie servers" icon="broom">
    ```python theme={null}
    agent.clean(force=True)
    agent.init()
    ```
  </Accordion>

  <Accordion title="Check device connection" icon="mobile">
    ```bash theme={null}
    # Android
    adb devices

    # iOS
    idevice_id -l
    ```
  </Accordion>

  <Accordion title="Enable debug logging" icon="bug">
    ```python theme={null}
    import logging
    logging.basicConfig(level=logging.DEBUG)
    ```
  </Accordion>

  <Accordion title="Enable tracing" icon="video">
    ```python theme={null}
    task = agent.new_task(goal).with_trace_recording(True).build()
    ```
  </Accordion>

  <Accordion title="Reset ADB" icon="rotate">
    ```bash theme={null}
    adb kill-server
    adb start-server
    ```
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="SDK Reference" icon="file-code" href="/docs/mobile-use-sdk/sdk-reference/agent">
    Complete SDK documentation
  </Card>

  <Card title="Examples" icon="code" href="/docs/mobile-use-sdk/examples/simple-photo-organizer">
    Working code examples
  </Card>
</CardGroup>