yt-dlp/yt-dlp · error · ExtractorError

Unable to login. Twitch said: {message}

Error message

Unable to login. Twitch said: {message}

What it means

Raised by TwitchBaseIE._perform_login via its fail() helper when Twitch's web login form rejects the submitted credentials. The {message} placeholder is the failure text parsed from Twitch's login HTML (wrong password, CAPTCHA required, unusual-activity block). It is an expected ExtractorError, i.e. a user/input problem, not an extractor bug.

Source

Thrown at yt_dlp/extractor/twitch.py:64

        'ClipsCards__User': '1cd671bfa12cec480499c087319f26d21925e9695d1f80225aae6a4354f23088',
        'ShareClipRenderStatus': '0a02bb974443b576f5579aab0fef1d4b7f44e58a8a256f0c5adfead0db70640f',
        'ChannelCollectionsContent': '5247910a19b1cd2b760939bf4cba4dcbd3d13bdf8c266decd16956f6ef814077',
        'StreamMetadata': 'ad022ca32220d5523d03a23cbcb5beaa1e0999889c1f8f78f9f2520dafb5cae6',
        'ComscoreStreamingQuery': 'e1edae8122517d013405f237ffcc124515dc6ded82480a88daef69c83b53ac01',
        'VideoPreviewOverlay': '9515480dee68a77e667cb19de634739d33f243572b007e98e67184b1a5d8369f',
        'VideoMetadata': '45111672eea2e507f8ba44d101a61862f9c56b11dee09a15634cb75cb9b9084d',
        'VideoPlayer_ChapterSelectButtonVideo': '71835d5ef425e154bf282453a926d99b328cdc5e32f36d3a209d0f4778b41203',
        'VideoPlayer_VODSeekbarPreviewVideo': '07e99e4d56c5a7c67117a154777b0baf85a5ffefa393b213f4bc712ccaf85dd6',
    }

    @property
    def _CLIENT_ID(self):
        return self._configuration_arg(
            'client_id', ['ue6666qo983tsx6so1t0vnawi233wa'], ie_key='Twitch', casesense=True)[0]

    def _perform_login(self, username, password):
        def fail(message):
            raise ExtractorError(
                f'Unable to login. Twitch said: {message}', expected=True)

        def login_step(page, urlh, note, data):
            form = self._hidden_inputs(page)
            form.update(data)

            page_url = urlh.url
            post_url = self._search_regex(
                r'<form[^>]+action=(["\'])(?P<url>.+?)\1', page,
                'post url', default=self._LOGIN_POST_URL, group='url')
            post_url = urljoin(page_url, post_url)

            headers = {
                'Referer': page_url,
                'Origin': 'https://www.twitch.tv',
                'Content-Type': 'text/plain;charset=UTF-8',
            }

View on GitHub (pinned to 81ecd58b13)

Solutions

  1. Pass browser cookies instead of password login: yt-dlp --cookies-from-browser chrome <twitch-url> (or export cookies.txt and use --cookies); required for 2FA accounts and far more reliable
  2. Verify the username/password with a normal browser login; watch for typos, trailing spaces, or an expired password
  3. Update yt-dlp (yt-dlp -U or pip install -U yt-dlp); login-page parsing breaks when Twitch changes markup
  4. If on a VPN/datacenter IP, retry from a residential IP to avoid the CAPTCHA/unusual-activity rejection path

Example fix

# before
yt-dlp --username USER --password PASS https://www.twitch.tv/videos/123456789

# after
yt-dlp --cookies-from-browser chrome https://www.twitch.tv/videos/123456789
Defensive patterns

Strategy: fallback

Validate before calling

import yt_dlp.utils

# Prefer cookie auth up front; password login is the fragile path
def has_cookie_auth(opts):
    return bool(opts.get('cookiefile') or opts.get('cookiesfrombrowser'))

assert has_cookie_auth(ydl_opts) or (username and password), 'no Twitch auth configured'

Type guard

from yt_dlp.utils import ExtractorError

def is_twitch_login_rejection(e: BaseException) -> bool:
    return isinstance(e, ExtractorError) and str(e).startswith('Unable to login. Twitch said:')

Try / catch

from yt_dlp import YoutubeDL
from yt_dlp.utils import ExtractorError

try:
    with YoutubeDL({'username': u, 'password': p}) as ydl:
        ydl.download([url])
except ExtractorError as e:
    if str(e).startswith('Unable to login. Twitch said:'):
        # Twitch rejected the password flow: fall back to cookie auth
        with YoutubeDL({'cookiesfrombrowser': ('chrome',)}) as ydl:
            ydl.download([url])
    else:
        raise

Prevention

When it happens

Trigger: Downloading any Twitch URL with --username/--password: after POSTing the login form, the returned page indicates failure and fail(message) fires at yt_dlp/extractor/twitch.py:62-64. Typical embedded messages: 'incorrect username or password', CAPTCHA / 'prove you are human', or 'login attempt blocked due to unusual activity'.

Common situations: Twitch password login is brittle: accounts with 2FA/OAuth-only, logins from VPN/datacenter IPs triggering CAPTCHA, changed login-form markup in old yt-dlp versions, or simply wrong credentials. Cookie-based auth bypasses the whole password flow.

Related errors

AI-assisted analysis of yt-dlp/yt-dlp@81ecd58b13 (2026-08-22). Data as JSON: /api/errors/0be0f605094f3871. Report an issue: GitHub.