Troubleshooting Guide¶

# Use Python module syntax
python -m pip install spotifyscraper
# or
python3 -m pip install spotifyscraper

# Install pip if missing
curl https://bootstrap.pypa.io/get-pip.py -o get-pip.py
python get-pip.py

# Check Python version (needs 3.8+)
python --version

# Upgrade pip
pip install --upgrade pip

# Try different index
pip install -i https://pypi.org/simple/ spotifyscraper

# Install specific version
pip install spotifyscraper==2.0.0

# Install for current user only
pip install --user spotifyscraper

# Use virtual environment (recommended)
python -m venv myenv
source myenv/bin/activate  # Windows: myenv\Scripts\activate
pip install spotifyscraper

# Check if installed
import sys
print(sys.executable)  # Which Python?
print(sys.path)        # Where does Python look?

# List installed packages
import pkg_resources
installed = [pkg.key for pkg in pkg_resources.working_set]
print('spotifyscraper' in installed)

# Ensure you're in the right environment
which python  # or `where python` on Windows

# Reinstall
pip uninstall spotifyscraper
pip install spotifyscraper

# Check installation
python -c "import spotify_scraper; print(spotify_scraper.__version__)"

# Correct imports
from spotify_scraper import SpotifyClient  # ✓

# If you need to configure the client, use constructor parameters:
client = SpotifyClient(
    browser_type="selenium",
    log_level="DEBUG",
    cookie_file="cookies.txt"
)

# Note: The Config class mentioned in some examples is internal

from spotify_scraper import SpotifyClient
from spotify_scraper.utils import is_spotify_url

def diagnose_url(url):
    """Diagnose URL issues."""
    print(f"Checking: {url}")

    # Validate URL
    if not is_spotify_url(url):
        print("❌ Invalid Spotify URL")
        return

    print("✓ Valid Spotify URL")

    # Try extraction
    client = SpotifyClient(log_level="DEBUG")
    try:
        data = client.get_track_info(url)
        print("✓ Extraction successful")
        print(f"  Track: {data.get('name', 'Unknown')}")
    except Exception as e:
        print(f"❌ Extraction failed: {e}")
        print("\nPossible solutions:")
        print("1. Check if content is available in your region")
        print("2. Update SpotifyScraper: pip install --upgrade spotifyscraper")
        print("3. Try using a VPN")
        print("4. Report issue on GitHub if persists")

# Test
diagnose_url("https://open.spotify.com/track/...")

# If you need album names, extract the album separately
track = client.get_track_info(track_url)
if track.get('album') and track['album'].get('id'):
    album_url = f"https://open.spotify.com/album/{track['album']['id']}"
    album = client.get_album_info(album_url)
    track.get('album', {}).get('name', 'Unknown') = album.get('name', 'Unknown')

# This will NOT work - OAuth required
client = SpotifyClient(cookie_file="spotify_cookies.txt")
track = client.get_track_info_with_lyrics(url)
# track['lyrics'] will be None

def validate_cookies(cookie_file):
    """Check if cookies are valid."""
    try:
        client = SpotifyClient(cookie_file=cookie_file)
        # Try to get a private playlist (requires auth)
        # Note: Lyrics cannot be used for validation as they require OAuth

        # Instead, check if cookies work by trying authenticated actions
        print("✓ Cookies loaded successfully")
        # You can test with private playlists or other auth features
    except:
            print("❌ Cookies might be expired")
    except Exception as e:
        print(f"❌ Cookie error: {e}")

validate_cookies("spotify_cookies.txt")

import requests
try:
    response = requests.get("https://open.spotify.com", timeout=10)
    print(f"✓ Connected: {response.status_code}")
except Exception as e:
    print(f"❌ Connection failed: {e}")

# Note: Proxy configuration depends on browser type
# For requests browser, you would need to configure the session
# For selenium browser, you would configure the driver options
client = SpotifyClient(browser_type="requests")
# Proxy configuration is browser-specific

# For Selenium browser
client = SpotifyClient(browser_type="selenium")
# Note: Timeout configuration varies by browser type

# Update certificates
pip install --upgrade certifi

# For corporate networks, you might need:
export REQUESTS_CA_BUNDLE=/path/to/corporate/cert.pem
export SSL_CERT_FILE=/path/to/corporate/cert.pem

track = client.get_track_info(url)
if track.get('preview_url'):
    path = client.download_preview_mp3(url)
else:
    print("No preview available for this track")

import os

def safe_download(url, directory="downloads"):
    """Download with error checking."""
    # Ensure directory exists
    os.makedirs(directory, exist_ok=True)

    # Check write permissions
    test_file = os.path.join(directory, ".test")
    try:
        with open(test_file, 'w') as f:
            f.write("test")
        os.remove(test_file)
        print("✓ Directory is writable")
    except:
        print("❌ Cannot write to directory")
        return

    # Download
    try:
        path = client.download_preview_mp3(url, path=directory)
        print(f"✓ Downloaded to: {path}")
    except Exception as e:
        print(f"❌ Download failed: {e}")

# Install media dependencies
pip install "spotifyscraper[media]"
# or
pip install eyeD3 mutagen

# Fast - for most cases
client = SpotifyClient(browser_type="requests")

# Slower - only when needed
client = SpotifyClient(browser_type="selenium")

# Good
client = SpotifyClient()
for url in urls:
    data = client.get_track_info(url)

# Bad
for url in urls:
    client = SpotifyClient()  # Creating new instance each time
    data = client.get_track_info(url)

from functools import lru_cache

@lru_cache(maxsize=100)
def get_track_cached(url):
    """Cache track data in memory."""
    return client.get_track_info(url)

# Always close Selenium browsers
client = SpotifyClient(browser_type="selenium")
try:
    # Your code
    pass
finally:
    client.close()  # Important!

# Use raw strings or forward slashes
path = r"C:\Users\Name\Music"  # Raw string
path = "C:/Users/Name/Music"   # Forward slashes

# Install driver manager
pip install webdriver-manager

# It will auto-download drivers

# On macOS Catalina+, you might need
pip install --user spotifyscraper

# Ensure using ARM version
arch -arm64 pip install spotifyscraper

# Ubuntu/Debian
sudo apt-get update
sudo apt-get install python3-dev

# For Selenium
sudo apt-get install chromium-chromedriver

# Required for servers without display
client = SpotifyClient(browser_type="selenium")
# Selenium runs headless by default

import logging

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

# Or use client parameter
client = SpotifyClient(log_level="DEBUG")

def inspect_response(url):
    """Inspect what SpotifyScraper sees."""
    from spotify_scraper.browsers import create_browser

    browser = create_browser("requests")
    content = browser.get_page_content(url)

    # Save response for inspection
    with open("response.html", "w", encoding="utf-8") as f:
        f.write(content)

    print("Response saved to response.html")
    print(f"Size: {len(content)} bytes")

    # Check for common issues
    if "404" in content:
        print("⚠️ Might be 404 error")
    if "not available" in content.lower():
        print("⚠️ Content might not be available")

def print_version_info():
    """Print version information for debugging."""
    import sys
    import spotify_scraper

    print(f"Python: {sys.version}")
    print(f"SpotifyScraper: {spotify_scraper.__version__}")

    # Check optional dependencies
    try:
        import selenium
        print(f"Selenium: {selenium.__version__}")
    except:
        print("Selenium: Not installed")

    try:
        import eyed3
        print(f"eyeD3: {eyed3.version.version}")
    except:
        print("eyeD3: Not installed")

## Environment
- SpotifyScraper version: 2.0.0
- Python version: 3.10.0
- OS: Windows 10

## Code
```python
from spotify_scraper import SpotifyClient
client = SpotifyClient()
# Minimal code that shows the problem

Full error message here

### Where to Get Help

1. 📖 **Documentation**: [spotifyscraper.readthedocs.io](https://spotifyscraper.readthedocs.io)
2. 💬 **Discussions**: [GitHub Discussions](https://github.com/AliAkhtari78/SpotifyScraper/discussions)
3. 🐛 **Bug Reports**: [GitHub Issues](https://github.com/AliAkhtari78/SpotifyScraper/issues)
4. 📧 **Email**: See repository for maintainer contact

---

## Common Import Fixes

```python
# Correct imports
from spotify_scraper import (
    SpotifyClient,
    SpotifyScraperError,
    URLError,
    NetworkError,
    ExtractionError,
    AuthenticationError,
    MediaError
)

# Utility imports
from spotify_scraper.utils import (
    is_spotify_url,
    extract_id,
    convert_to_embed_url,
    get_url_type
)

# For bulk operations
from spotify_scraper.utils import (
    SpotifyBulkOperations,
    SpotifyDataAnalyzer
)