Troubleshooting - Wal33D/itch-dl GitHub Wiki

Troubleshooting

This page covers common issues and their solutions when using itch-dl.

🔑 API Key Issues

"You did not provide an API key"

Problem: itch-dl requires an API key for all operations.

Solutions:

  1. Get your API key from itch.io API Keys
  2. Use it with the --api-key flag: 
    itch-dl https://example.itch.io/game --api-key YOUR_API_KEY
  3. Or set it as an environment variable: 
    export ITCH_API_KEY="your_api_key_here"
itch-dl https://example.itch.io/game

"Provided API key appears to be invalid"

Problem: The API key is incorrect or expired.

Solutions:

  1. Double-check your API key from itch.io API Keys
  2. Generate a new API key if needed
  3. Ensure there are no extra spaces or characters

🐛 Fixed Issues

"TypeError: data.owned_keys is not iterable" (Fixed in v0.6.4)

Problem: This error occurred when users had no purchased games on itch.io.

Solution: Update to itch-dl v0.6.4 or later:

npm update -g itch-dl

What was fixed: The itch.io API returns owned_keys as an empty object {} instead of an empty array [] when a user has no purchases. v0.6.4 handles both cases correctly.

📥 Download Issues

Empty results for "my-purchases"

Problem: itch-dl https://itch.io/my-purchases returns no URLs.

This is normal if:

  • You haven't purchased any games on itch.io
  • You only have free games (which don't show in purchases)

Solutions:

  • Download free games individually by their URLs
  • Purchase games to add them to your library
  • Use collections or creator pages for bulk downloads

"No URLs to download"

Problem: The target page contains no downloadable games.

Possible causes:

  1. Empty collection: The collection has no games
  2. Private content: You don't have access to the games
  3. Invalid URL: The URL doesn't exist or is malformed
  4. Filtering: Your filters excluded all games

Solutions:

  1. Verify the URL in your browser
  2. Check if the collection/page is public
  3. Remove filters and try again
  4. Use --urls-only to see what URLs are found

Collection downloads fail

Problem: Collections return errors or no results.

Common causes:

  • Private collections: Only the owner can download
  • Expired collections: Some collections may be removed
  • Network issues: Temporary connectivity problems

Solutions:

  1. Ensure the collection is public
  2. Test with a known working collection: https://itch.io/c/215689/public-collection
  3. Check your internet connection

🌐 Network Issues

Network timeouts

Problem: Downloads time out or fail due to slow connections.

Solutions:

  1. Reduce concurrency: 
    itch-dl URL --parallel 1 --api-key YOUR_KEY
  2. Use a different network connection
  3. Try again later (itch.io servers may be busy)

Rate limiting

Problem: Too many requests cause temporary blocks.

Solutions:

  1. Reduce parallel downloads: --parallel 1
  2. Wait a few minutes before retrying
  3. Avoid running multiple itch-dl instances simultaneously

🎮 Game-Specific Issues

Game downloads but files are missing

Problem: Download completes but expected files aren't there.

Possible causes:

  1. Free game with no files: Some pages are just descriptions
  2. Platform filtering: Files filtered out by platform restrictions
  3. Access restrictions: Game requires purchase or special access

Solutions:

  1. Check if the game actually has downloadable files
  2. Remove platform filters: don't use --filter-files-platform
  3. Verify the game isn't purchase-only

Large games fail to download

Problem: Big games (>1GB) fail during download.

Solutions:

  1. Check available disk space
  2. Use a stable internet connection
  3. Try downloading to a different directory
  4. Download one game at a time: --parallel 1

📱 Platform Issues

Linux/macOS permission errors

Problem: Can't write to download directory.

Solutions:

  1. Use a directory you own: --download-to ~/Downloads/itch
  2. Check directory permissions: ls -la
  3. Create the directory first: mkdir -p ~/Downloads/itch

Windows path issues

Problem: Paths with spaces or special characters fail.

Solutions:

  1. Use quotes around paths: --download-to "C:\My Games\itch"
  2. Avoid special characters in directory names
  3. Use forward slashes: --download-to C:/Games/itch

🔍 Debugging

Enable verbose logging

Get more detailed output for debugging:

itch-dl URL --verbose --api-key YOUR_KEY

Test with --urls-only

See what URLs are being found without downloading:

itch-dl URL --urls-only --api-key YOUR_KEY

Check specific game

Test with a known working game:

itch-dl https://ncase.itch.io/anxiety --urls-only --api-key YOUR_KEY

🆘 Getting Help

If you're still having issues:

  1. Check existing issues: GitHub Issues
  2. Update to latest version: npm update -g itch-dl
  3. Test with a known working example from Tested Games
  4. Create a new issue with:
    • Your itch-dl version: itch-dl --version
    • The exact command you ran
    • The full error message
    • Your operating system

📋 Common Solutions Checklist

Before reporting an issue, try these:

  • Updated to the latest version
  • Verified your API key works
  • Tested with a known working URL
  • Checked the URL in your browser
  • Tried with --urls-only first
  • Used --verbose for more details
  • Checked available disk space
  • Verified internet connection

Last Updated: 2025-07-15 (v0.6.4)