🔧 Troubleshooting

This section provides practical solutions to common issues you might encounter while installing, configuring, or using the SDK.

Each problem is accompanied by clear steps to help you quickly resolve the issue and resume your development.

⚙️ Common Installation and Usage Issues

1. ImportError: No module named 'wyseos.mate'

Cause: This error indicates that the Python interpreter cannot locate the wyseos.mate package, usually because it's not installed or your virtual environment is not active.

Solution:

• Verify Installation: Ensure the SDK is properly installed. Re-run the installation command:

  pip install wyseos-sdk

• Activate Virtual Environment: If you are using a virtual environment (highly recommended), ensure it is activated before running your Python script.

  # For Linux/macOS users:
  source mate-sdk-env/bin/activate
  
  # For Windows users (Command Prompt):
  mate-sdk-env\Scripts\activate.bat
  
  # For Windows users (PowerShell):
  mate-sdk-env\Scripts\Activate.ps1

2. ConfigError: Configuration file not found: mate.yaml

Cause: The SDK client was initialized without successfully loading a mate.yaml configuration file.

Solution:

• Create mate.yaml: Create a mate.yaml file in your project's root directory, ensuring it contains your API key and other necessary configurations. Refer to the Authentication guide for the correct format.
• In-Code Configuration: As an alternative (less recommended for production), you can directly pass ClientOptions when initializing the Client in your Python code.

3. SSLCertificateError: [SSL: CERTIFICATE_VERIFY_FAILED]

Cause: This error typically arises from issues with SSL certificate verification, often due to an outdated or missing certificate bundle on your operating system.

Solution:

• Update System SSL Certificates: The method for updating SSL certificates varies by operating system.

  • macOS: For Python installations managed by python.org (not Homebrew), you might need to run the Install Certificates.command script located in your Python application directory (e.g., /Applications/Python 3.x/Install Certificates.command).

• Disable SSL Verification (Use with Extreme Caution): For development or testing environments, you can disable SSL verification. This is not recommended for production due to significant security risks.

  from wyseos.mate import Client, ClientOptions
  import requests
  
  # Create a requests session that bypasses SSL certificate verification
  # WARNING: This practice exposes your application to security vulnerabilities.
  session = requests.Session()
  session.verify = False
  
  client = Client(ClientOptions(
      api_key="YOUR_API_KEY", # Replace with your actual API key
      # http_client is not a valid parameter anymore
  ))
  print("Client initialized with SSL verification disabled.")

4. PermissionError: [Errno 13] Permission denied during pip install

Cause: You lack the necessary permissions to install packages globally on your system.

Solution:

• Use a Virtual Environment (Recommended): This is the safest and most effective way to manage Python dependencies, as it installs packages into an isolated environment that doesn't require system-wide permissions.

• Install with --user Flag: This installs the package only for your current user, typically in ~/.local/lib/pythonX.Y/site-packages/.

  pip install --user wyseos-sdk

5. ConfigError: Invalid YAML in configuration file

Cause: Your mate.yaml configuration file contains syntax errors.

Solution: Carefully review your mate.yaml for correct YAML syntax. Pay close attention to:

• Indentation: YAML relies heavily on consistent indentation using spaces (not tabs).

• Colons: Ensure proper use of colons (:) to separate keys and values.

• Quoting: String values, especially those containing special characters, should be enclosed in double quotes (").

  Consider using an online YAML validator to quickly identify and fix syntax errors.

✅ Configuration Validation Errors

The SDK rigorously validates your ClientOptions to ensure that all required configurations are present and correctly formatted. Here are common ValidationError messages you might encounter:

Missing API Key (api_key)

Error Message Example: Validation Error: API key must not be empty

Cause: The api_key field in your ClientOptions (or mate.yaml) is missing or empty.

Solution: Provide a valid API key obtained from your WyseOS dashboard.

from wyseos.mate import Client, ClientOptions
from wyseos.mate.errors import ValidationError

try:
    client = Client(ClientOptions(api_key="")) # Incorrect: Empty API key
except ValidationError as e:
    print(f"Correctly caught: {e}") # Expected output: Validation Error: API key must not be empty

Invalid Base URL (base_url)

Error Message Example: Validation Error: base_url must be a valid URL

Cause: The base_url provided in ClientOptions (or mate.yaml) is not a properly formatted URL.

Solution: Ensure the base_url is a complete and valid URL, including the scheme (e.g., https://).

from wyseos.mate import Client, ClientOptions
from wyseos.mate.errors import ValidationError

try:
    client = Client(ClientOptions(api_key="YOUR_API_KEY", base_url="invalid-url")) # Incorrect: Malformed URL
except ValidationError as e:
    print(f"Correctly caught: {e}") # Expected output: Validation Error: base_url must be a valid URL

Invalid Timeout Value (timeout)

Error Message Example: Validation Error: timeout must be a positive integer

Cause: The timeout value in ClientOptions (or mate.yaml) is zero, negative, or not an integer.

Solution: Provide a positive integer for the timeout parameter, representing seconds.

from wyseos.mate import Client, ClientOptions
from wyseos.mate.errors import ValidationError

try:
    client = Client(ClientOptions(api_key="YOUR_API_KEY", timeout=0)) # Incorrect: Timeout cannot be zero
except ValidationError as e:
    print(f"Correctly caught: {e}") # Expected output: Validation Error: timeout must be a positive integer

🤖 TaskRunner-Specific Issues (v0.2.1+)

With the introduction of the TaskRunner interface in v0.2.1, you might encounter new types of issues. Here are the most common problems and their solutions:

1. ImportError: cannot import name 'TaskExecutionOptions'

Cause: You're using an older version of the SDK that doesn't include the TaskRunner interface.

Solution:

• Upgrade to v0.2.1+: Ensure you have the latest SDK version installed:

  pip install --upgrade wyseos-sdk

• Verify Version: Check your installed version:

  import wyseos.mate
  print(f"SDK Version: {wyseos.mate.__version__}")
  # Should be 0.2.1 or higher

2. TaskRunner.run_task() Hangs or Times Out

Cause: The task is taking longer than the configured timeout, or there's an issue with the WebSocket connection.

Solution:

• Increase Timeout: Extend the completion timeout for complex tasks:

  from wyseos.mate.websocket import TaskExecutionOptions
  
  options = TaskExecutionOptions(
      completion_timeout=900  # 15 minutes for complex tasks
  )
  result = task_runner.run_task("Complex analysis task", "team_id", options)

• Check WebSocket Connection: Verify your network connectivity and firewall settings.

• Enable Debug Logging: Get more insights into what's happening:

  import logging
  logging.basicConfig(level=logging.DEBUG)
  
  options = TaskExecutionOptions(enable_event_logging=True)
  result = task_runner.run_task(task, team_id, options)
  
  # Review execution logs
  for log in result.execution_logs:
      print(f"{log.get('timestamp')}: {log.get('message')}")

3. TaskResult.success is False with Unclear Error

Cause: The task execution failed due to various reasons like invalid team_id, insufficient permissions, or task complexity.

Solution:

• Check Error Details: Always examine the error field:

  result = task_runner.run_task(task, team_id)
  if not result.success:
      print(f"Task failed: {result.error}")
      print(f"Execution logs: {result.execution_logs}")

• Verify Team Access: Ensure the team_id exists and you have access:

  teams = client.team.get_list("all")
  available_teams = [team.team_id for team in teams.data]
  print(f"Available teams: {available_teams}")

• Simplify the Task: Try a simpler task first to verify the setup:

  simple_result = task_runner.run_task("Say hello", team_id)
  if simple_result.success:
      print("Basic functionality works, issue might be with task complexity")

4. Memory Issues with Large Screenshots

Cause: Enabling capture_screenshots=True can consume significant memory for long-running tasks.

Solution:

• Disable Screenshots for Performance: Only enable when needed:

  # Production configuration - faster, less memory
  production_options = TaskExecutionOptions(
      capture_screenshots=False,
      enable_browser_logging=False
  )
  
  # Debug configuration - more data, higher memory usage
  debug_options = TaskExecutionOptions(
      capture_screenshots=True,
      enable_browser_logging=True
  )

• Process Screenshots Incrementally: For debugging, handle screenshots in batches rather than storing all in memory.

5. run_interactive_session() Not Responding to Input

Cause: The interactive session might not be properly configured for user input, or there are timeout issues.

Solution:

• Configure Interactive Settings: Ensure proper options for interactive use:

  interactive_options = TaskExecutionOptions(
      auto_accept_plan=False,        # Require manual approval
      max_user_input_timeout=0,      # No timeout for user input
      enable_event_logging=True      # See what's happening
  )
  
  task_runner.run_interactive_session(
      "Interactive task",
      team_id,
      interactive_options
  )

• Check Console Output: Ensure you're monitoring the console for prompts and messages.

6. Dependency Conflicts with python-socks

Cause: v0.2.1 introduced python-socks >= 2.7.0 as a new dependency, which might conflict with existing packages.

Solution:

• Update Dependencies: Upgrade all related packages:

  pip install --upgrade wyseos-sdk python-socks

• Use Virtual Environment: Isolate dependencies to avoid conflicts:

  python -m venv wyseos-env
  source wyseos-env/bin/activate  # On Windows: wyseos-env\Scripts\activate
  pip install wyseos-sdk

• Check Dependency Tree: Identify conflicting packages:

  pip show wyseos-sdk
  pip list | grep socks

❓ Need Further Assistance?

If your issue is not covered here or you require more in-depth support, please utilize the following resources:

• GitHub Issues: For bug reports, feature requests, or contributions, please open an issue on our GitHub repository. Provide as much detail as possible, including steps to reproduce, error messages, and your environment setup.
• Support Email: For direct assistance with account-specific issues or confidential inquiries, reach out to our support team at [email protected].