Common Issues

This page covers the most common issues you might encounter when using the Clio SDK and how to resolve them.

Installation Issues

ImportError: No module named ‘clio’

Problem: Python can’t find the Clio SDK module.

Solutions:

1. Check if installed:

   pip list | grep clio

2. Install the SDK:

   pip install clio

3. Virtual environment issues:

   # Make sure you're in the right environment
   which python
   which pip
   
   # Activate your virtual environment
   source venv/bin/activate  # Linux/macOS
   # or
   venv\Scripts\activate     # Windows

4. Development installation:

   # If installing from source
   cd clio-sdk/sdk
   pip install -e .

Playwright Installation Issues

Problem: Playwright browsers not installed or not working.

Solutions:

1. Install Playwright and browsers:

   pip install playwright
   playwright install

2. Install specific browsers:

   playwright install chromium  # Just Chromium
   playwright install --with-deps  # Include system dependencies

3. Permission issues (Linux):

   sudo playwright install-deps

Authentication Issues

”Invalid API key format” Error

Problem: API key doesn’t start with clio_ or is malformed.

Solutions:

1. Check API key format:

   api_key = os.getenv("CLIO_API_KEY")
   print(f"API key starts with 'clio_': {api_key.startswith('clio_') if api_key else False}")

2. Get a new API key:

   • Log into your Clio dashboard
   • Go to Settings → API Keys
   • Generate a new key
   • Copy the entire key including clio_ prefix

3. Check for whitespace:

   # Trim whitespace
   api_key = os.getenv("CLIO_API_KEY", "").strip()

ClioAuthError: “Invalid API key”

Problem: API key format is correct but authentication fails.

Solutions:

1. Verify key is active:

   • Check your Clio dashboard
   • Ensure the API key hasn’t been revoked
   • Try generating a new key

2. Check server URL:

   # Make sure you're connecting to the right server
   monitor = ClioMonitor(
       api_key="clio_your_key",
       base_url="https://api.cliomonitoring.com"  # Correct URL
   )

3. Network connectivity:

   # Test connectivity
   curl -I https://api.cliomonitoring.com

Environment Variable Not Set

Problem: CLIO_API_KEY environment variable is not found.

Solutions:

1. Set environment variable:

   export CLIO_API_KEY="clio_your_key_here"

2. Use .env file:

   # Create .env file
   echo "CLIO_API_KEY=clio_your_key_here" > .env

   # Load in Python
   from dotenv import load_dotenv
   load_dotenv()

3. Check current environment:

   import os
   print("Environment variables:")
   for key, value in os.environ.items():
       if "CLIO" in key:
           print(f"{key}=***masked***")

Video Recording Issues

No Video Files Created

Problem: Playwright isn’t creating video files.

Solutions:

1. Enable video recording:

   context = await browser.new_context(
       record_video_dir="./videos",  # Must be set
       record_video_size={"width": 1280, "height": 720}
   )

2. Check directory exists:

   import os
   os.makedirs("./videos", exist_ok=True)

3. Verify permissions:

   ls -la videos/
   chmod 755 videos/  # Ensure writable

4. Check for video files:

   from pathlib import Path
   video_files = list(Path("./videos").glob("*.webm"))
   print(f"Found videos: {video_files}")

Video Files Not Uploaded

Problem: Video files are created but not uploaded to Clio.

Solutions:

1. Check monitoring was started:

   await monitor.start_run(context, "Test Name")  # Must call this

2. Ensure context.close() is called:

   try:
       # Your automation code
       pass
   finally:
       await context.close()  # Upload happens here

3. Check for upload errors:

   monitor = ClioMonitor(
       api_key="clio_key",
       raise_on_error=True  # See upload errors
   )

4. Verify network connectivity:

   # Test with shorter timeout to see errors faster
   monitor = ClioMonitor(api_key="clio_key", timeout=10)

Upload Issues

ClioUploadError: “Upload timed out”

Problem: Large files timing out during upload.

Solutions:

1. Increase timeout:

   monitor = ClioMonitor(
       api_key="clio_key",
       timeout=300  # 5 minutes
   )

2. Check file sizes:

   from pathlib import Path
   for video in Path("./videos").glob("*.webm"):
       size_mb = video.stat().st_size / (1024 * 1024)
       print(f"{video.name}: {size_mb:.1f} MB")

3. Reduce video quality (if files are very large):

   context = await browser.new_context(
       record_video_dir="./videos",
       record_video_size={"width": 1280, "height": 720}  # Smaller size
   )

Upload Retries Exhausted

Problem: All retry attempts fail.

Solutions:

1. Increase retry attempts:

   monitor = ClioMonitor(
       api_key="clio_key",
       retry_attempts=5  # More retries
   )

2. Check network stability:

   ping api.cliomonitoring.com

3. Use exponential backoff manually:

   import asyncio
   
   for attempt in range(3):
       try:
           await monitor.start_run(context, "Test")
           break
       except ClioUploadError:
           if attempt < 2:
               await asyncio.sleep(2 ** attempt)
           else:
               raise

Configuration Issues

SSL Certificate Errors

Problem: SSL verification failures.

Solutions:

1. For development only - disable SSL verification:

   monitor = ClioMonitor(
       api_key="clio_key",
       verify_ssl=False  # Only for localhost/development
   )

2. Update certificates:

   # Update system certificates
   pip install --upgrade certifi

3. Corporate proxy/firewall:

   # May need custom configuration for corporate environments
   # Check with your IT department

Base URL Configuration

Problem: Can’t connect to custom Clio server.

Solutions:

1. Check URL format:

   # Correct formats
   base_url = "https://api.cliomonitoring.com"           # Production
   base_url = "http://localhost:8000"         # Local dev
   base_url = "https://staging.cliomonitoring.com"      # Staging
   
   # Incorrect formats
   base_url = "api.cliomonitoring.com"                  # Missing protocol
   base_url = "ftp://api.cliomonitoring.com"           # Wrong protocol

2. Test connectivity:

   curl -I http://localhost:8000/health

Performance Issues

Slow Upload Times

Problem: Uploads taking too long.

Solutions:

1. Check file sizes:

   # Large videos take longer to upload
   # Consider shorter test scenarios

2. Network optimization:

   # Use concurrent uploads (automatic in SDK)
   # Ensure good network connection

3. Monitor upload progress:

   import logging
   logging.basicConfig(level=logging.DEBUG)
   # Will show upload progress for large files

Memory Issues with Large Files

Problem: Out of memory errors with large video files.

Solutions:

1. SDK automatically streams large files (>10MB), but you can:

   # Reduce video recording time
   # Split long tests into smaller chunks

2. Monitor memory usage:

   import psutil
   process = psutil.Process()
   print(f"Memory usage: {process.memory_info().rss / 1024 / 1024:.1f} MB")

Rate Limiting Issues

ClioRateLimitError: “Monthly rate limit exceeded”

Problem: Exceeded your monthly upload quota.

Solutions:

1. Check your usage:

   • Log into Clio dashboard
   • View usage statistics
   • Consider upgrading your plan

2. Optimize test frequency:

   # Run monitoring only on important tests
   # Skip monitoring for local development
   if os.getenv("ENVIRONMENT") == "production":
       await monitor.start_run(context, "Test")

3. Batch testing:

   # Combine multiple test cases into single runs
   # Reduce number of separate uploads

Debugging Tips

Enable Debug Logging

import logging
logging.basicConfig(
    level=logging.DEBUG,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
)

# Now you'll see detailed SDK logs

Test Configuration

def test_clio_setup():
    """Test Clio configuration before running automation"""
    try:
        api_key = os.getenv("CLIO_API_KEY")
        if not api_key:
            print("❌ CLIO_API_KEY not set")
            return False

        if not api_key.startswith("clio_"):
            print("❌ Invalid API key format")
            return False

        monitor = ClioMonitor(api_key=api_key)
        print("✅ ClioMonitor created successfully")
        return True

    except Exception as e:
        print(f"❌ Configuration error: {e}")
        return False

# Run before your automation
if not test_clio_setup():
    exit(1)

Check SDK Version

import clio
print(f"Clio SDK version: {clio.__version__}")

# Update if needed
# pip install --upgrade clio

Getting Help

If you’re still having issues:

1. Check the logs - Enable debug logging to see detailed information
2. Test with minimal example - Use the basic example to isolate issues
3. Check the dashboard - Look for error messages in your Clio dashboard
4. Update dependencies - Ensure you’re using the latest SDK version
5. Contact support - Reach out with specific error messages and logs

Minimal Reproduction Case

When reporting issues, create a minimal example:

import os
from clio import ClioMonitor

# Minimal test case
api_key = os.getenv("CLIO_API_KEY", "clio_test_key_for_format_check")

try:
    monitor = ClioMonitor(api_key=api_key, raise_on_error=True)
    print("✅ Basic initialization works")
except Exception as e:
    print(f"❌ Error: {e}")
    # Include this error message when reporting issues