Skip to main content
This guide covers common issues you may encounter when using twitter-cli and their solutions.

​
Authentication Issues

Error message:
No Twitter cookies found.
Option 1: Set TWITTER_AUTH_TOKEN and TWITTER_CT0 environment variables
Option 2: Make sure you are logged into x.com in your browser
Cause:
  • You’re not logged into x.com in any supported browser (Chrome, Edge, Firefox, Brave)
  • OR the browser-cookie3 library cannot access your browser’s cookie store
Solution:
  1. Log in to x.com in one of the supported browsers
  2. Verify you’re logged in by visiting https://x.com and confirming you see your timeline
  3. Retry the command
Alternative: Set environment variables manually:
export TWITTER_AUTH_TOKEN="your_auth_token_here"
export TWITTER_CT0="your_ct0_token_here"
How to find cookies manually:
  1. Open x.com in your browser
  2. Open Developer Tools (F12)
  3. Go to Application → Cookies → https://x.com
  4. Copy the values for auth_token and ct0
Reference: twitter_cli/auth.py:254-300
Error: Browser cookie extraction fails silently or returns “browser-cookie3 not installed”Solution: Install the browser-cookie3 dependency:
# If installed via uv tool
uv tool install --force --with browser-cookie3 twitter-cli

# If installed via pipx
pipx inject twitter-cli browser-cookie3

# If using uv sync for development
uv sync
Reference: twitter_cli/auth.py:126-149

​
API Errors

Error message:
Twitter API error 404: ...
Cause:
  • Twitter/X has rotated their GraphQL query IDs (this happens periodically)
  • The hardcoded fallback query IDs in the CLI are outdated
What happens: The CLI automatically attempts to recover by:
  1. Fetching live query IDs from Twitter’s JavaScript bundles
  2. Falling back to community-maintained query IDs from GitHub
Solution:
  • Simply retry the command — the CLI will use the refreshed query ID
  • The fix is automatic; no manual intervention needed
If the error persists:
  • Check if Twitter/X is experiencing an outage
  • Update to the latest version: uv tool install --upgrade twitter-cli
Reference: twitter_cli/client.py:629-646
Error message:
Rate limited (429), retrying in X.Xs (attempt Y/3)
or
Rate limited: ... (try again later, recommended wait: 15+ minutes)
Cause:
  • Twitter has rate-limited your IP or account
  • Too many requests in a short time period
  • Write operations (like, retweet, bookmark) have daily/hourly limits
Solution:
  1. Wait: The CLI automatically retries with exponential backoff
  2. For write operations: Wait at least 15-30 minutes before retrying
  3. Reduce request volume: 
    # Use smaller --max values
twitter feed --max 20   # instead of --max 500
  4. Increase delays in config.yaml: 
    rateLimit:
  requestDelay: 5.0       # increase from default 2.5s
  maxRetries: 3
  retryBaseDelay: 10.0    # increase from default 5.0s
  5. Use a proxy to distribute requests: 
    export TWITTER_PROXY=http://127.0.0.1:7890
Reference: twitter_cli/client.py:747-826
Error message:
Twitter API returned invalid JSON
Cause:
  • Twitter returned an error page or non-JSON response
  • Network interruption or proxy interference
Solution:
  1. Check your internet connection
  2. If using a proxy, verify it’s working correctly
  3. Retry the command
  4. Check Twitter/X status at https://status.twitterstat.us/
Reference: twitter_cli/client.py:786-789

​
Data Issues

Error message:
Invalid tweet JSON file: ...
Cause:
  • The JSON file passed to --input is corrupted or in the wrong format
  • File was manually edited incorrectly
Solution:
  1. Regenerate the JSON file: 
    twitter feed --json > tweets.json
  2. Verify JSON syntax: 
    python3 -m json.tool tweets.json > /dev/null
  3. Don’t manually edit exported JSON files unless you’re familiar with the schema
Reference: twitter_cli/cli.py:65-77
Error message:
User @username not found
Cause:
  • The username doesn’t exist
  • The account has been suspended or deleted
  • The account is private and you don’t have access
Solution:
  • Verify the username spelling
  • Check if the account exists by visiting https://x.com/username
  • For private accounts, ensure you follow them from your logged-in account
Reference: twitter_cli/client.py:339-380

​
Configuration Issues

Error message:
--max must be greater than 0
Cause: You passed --max 0 or a negative numberSolution:
# Use a positive number
twitter feed --max 20
Reference: twitter_cli/cli.py:93-100
Symptom: Your config.yaml settings are being ignoredSolution:
  1. Verify file location — the CLI looks for:
    • ./config.yaml (current directory)
    • <project-root>/config.yaml
  2. Check YAML syntax: 
    python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"
  3. Example valid config: 
    fetch:
  count: 50

filter:
  mode: "topN"
  topN: 20
  weights:
    likes: 1.0
    retweets: 3.0

rateLimit:
  requestDelay: 2.5
  maxRetries: 3
Reference: twitter_cli/config.py:41-67

​
Connection Issues

Symptom: Requests timeout or fail when TWITTER_PROXY is setSolution:
  1. Verify proxy URL format: 
    # HTTP proxy
export TWITTER_PROXY=http://127.0.0.1:7890

# SOCKS5 proxy
export TWITTER_PROXY=socks5://127.0.0.1:1080
  2. Test proxy connectivity: 
    curl --proxy $TWITTER_PROXY https://x.com
  3. Verify proxy supports HTTPS
Reference: twitter_cli/client.py:122-138
Error: SSL certificate verification fails or TLS handshake errorsCause:
  • Corporate proxy with SSL inspection
  • Outdated system certificates
  • Antivirus/firewall interference
Solution:
  1. If behind a corporate proxy, configure it properly: 
    export TWITTER_PROXY=http://proxy.company.com:8080
  2. Update system certificates (Linux): 
    sudo update-ca-certificates
  3. Update curl_cffi: 
    uv tool install --upgrade twitter-cli
Reference: twitter_cli/client.py:122-148

​
Performance Issues

Symptom: CLI takes 5-10 seconds to start before showing resultsCause: The CLI initializes by:
  • Fetching x.com homepage to extract anti-detection headers
  • Scanning JavaScript bundles for live query IDs
  • Extracting browser cookies
This is expected behavior — startup fetches are required for anti-detection.To minimize:
  • Don’t run the CLI too frequently (cookies are cached for 24h)
  • Use --input to reprocess previously fetched JSON instead of re-fetching
Reference: twitter_cli/client.py:648-681

​
Best Practices to Avoid Issues

  1. Use a proxy to avoid IP-based rate limiting: 
    export TWITTER_PROXY=http://127.0.0.1:7890
  2. Keep request volumes low: 
    twitter feed --max 20  # Don't use --max 500
  3. Don’t run too frequently — each run fetches x.com to initialize headers
  4. Use browser cookie extraction for full browser fingerprint instead of manual tokens
  5. Avoid datacenter IPs — residential proxies are much safer
  6. Update regularly: 
    uv tool install --upgrade twitter-cli

​
Getting Help

If you encounter an issue not covered here:
  1. Enable debug logging: 
    twitter --verbose feed
  2. Check the logs in the error output for specific file/line references
  3. Report issues at: https://github.com/jackwener/twitter-cli/issues
Include:
  • The full error message
  • Command you ran
  • OS and Python version
  • Whether you’re using a proxy

Build docs developers (and LLMs) love

Get started for freeTalk to us