ytdl-org/youtube-dl · error · ExtractorError

invalid download number %s for query "%s"

Error message

invalid download number %s for query "%s"

What it means

Error "invalid download number %s for query "%s"" thrown in ytdl-org/youtube-dl.

Source

Thrown at youtube_dl/extractor/common.py:3394

    @classmethod
    def suitable(cls, url):
        return re.match(cls._make_valid_url(), url) is not None

    def _real_extract(self, query):
        mobj = re.match(self._make_valid_url(), query)
        if mobj is None:
            raise ExtractorError('Invalid search query "%s"' % query)

        prefix = mobj.group('prefix')
        query = mobj.group('query')
        if prefix == '':
            return self._get_n_results(query, 1)
        elif prefix == 'all':
            return self._get_n_results(query, self._MAX_RESULTS)
        else:
            n = int(prefix)
            if n <= 0:
                raise ExtractorError('invalid download number %s for query "%s"' % (n, query))
            elif n > self._MAX_RESULTS:
                self._downloader.report_warning('%s returns max %i results (you requested %i)' % (self._SEARCH_KEY, self._MAX_RESULTS, n))
                n = self._MAX_RESULTS
            return self._get_n_results(query, n)

    def _get_n_results(self, query, n):
        """Get a specified number of results for a query"""
        raise NotImplementedError('This method must be implemented by subclasses')

    @property
    def SEARCH_KEY(self):
        return self._SEARCH_KEY

View on GitHub (pinned to 956b8c5855)

Solutions

1. Use a valid download number for the query, e.g. ytsearch5:term with a positive integer.

When it happens

Trigger: Thrown at youtube_dl/extractor/common.py:3394 when the library encounters an invalid state.

Common situations: See trigger scenarios.

AI-assisted analysis of ytdl-org/youtube-dl@956b8c5855 (2026-08-14). Data as JSON: /api/errors/3e546682824e0fa9. Report an issue: GitHub.