ytdl-org/youtube-dl · error · ValueError

Playlist start must be positive

Error message

Playlist start must be positive

What it means

Raised by youtube-dl's Windows UTF-8 console writer (write_string path) when a call to the Win32 API WriteConsoleW returns 0 — i.e. the console rejected the write — after the code has already carefully chunked the string to handle non-BMP (astral) characters as surrogate pairs. 'Failed to write string' therefore means the console handle itself failed, not a Unicode-edge-case bug in chunking.

Source

Thrown at youtube_dl/__init__.py:204

            except (TypeError, ValueError):
                parser.error('invalid retry count specified')
        return parsed_retries
    if opts.retries is not None:
        opts.retries = parse_retries(opts.retries)
    if opts.fragment_retries is not None:
        opts.fragment_retries = parse_retries(opts.fragment_retries)
    if opts.buffersize is not None:
        numeric_buffersize = FileDownloader.parse_bytes(opts.buffersize)
        if numeric_buffersize is None:
            parser.error('invalid buffer size specified')
        opts.buffersize = numeric_buffersize
    if opts.http_chunk_size is not None:
        numeric_chunksize = FileDownloader.parse_bytes(opts.http_chunk_size)
        if not numeric_chunksize:
            parser.error('invalid http chunk size specified')
        opts.http_chunk_size = numeric_chunksize
    if opts.playliststart <= 0:
        raise ValueError('Playlist start must be positive')
    if opts.playlistend not in (-1, None) and opts.playlistend < opts.playliststart:
        raise ValueError('Playlist end must be greater than playlist start')
    if opts.extractaudio:
        if opts.audioformat not in ['best', 'aac', 'flac', 'mp3', 'm4a', 'opus', 'vorbis', 'wav']:
            parser.error('invalid audio format specified')
    if opts.audioquality:
        opts.audioquality = opts.audioquality.strip('k').strip('K')
        if not opts.audioquality.isdigit():
            parser.error('invalid audio quality specified')
    if opts.recodevideo is not None:
        if opts.recodevideo not in ['mp4', 'flv', 'webm', 'ogg', 'mkv', 'avi']:
            parser.error('invalid video recode format specified')
    if opts.convertsubtitles is not None:
        if opts.convertsubtitles not in ['srt', 'vtt', 'ass', 'lrc']:
            parser.error('invalid subtitle format specified')

    if opts.date is not None:
        date = DateRange.day(opts.date)

View on GitHub (pinned to 956b8c5855)

Solutions

1. If you do not need console colors/Unicode, redirect output: youtube-dl ... > out.log 2>&1, which bypasses the WriteConsoleW path entirely (falls back to normal stream writes).
2. Set PYTHONIOENCODING=utf-8 or run via python -X utf8 to steer encoding behavior on newer Pythons.
3. Update youtube-dl / move to yt-dlp; console output handling on Windows has been hardened significantly.
4. If embedding, wrap the download call and treat OSError from the output layer as a stop signal (the console is gone) rather than retrying.

Example fix

# before: writing directly, console may reject
write_string(message + '\n', sys.stderr)

# after: guard the console-write path
try:
    write_string(message + '\n', sys.stderr)
except OSError:
    with open('youtube-dl.log', 'a', encoding='utf-8') as f:
        f.write(message + '\n')

import sys

def console_ok():
    # only trust a real, healthy console handle on Windows
    if sys.platform != 'win32':
        return True
    import ctypes
    return ctypes.windll.kernel32.GetConsoleMode(
        ctypes.windll.kernel32.GetStdHandle(-12), ctypes.byref(ctypes.c_uint32())
    ) != 0

from youtube_dl.utils import write_string
try:
    write_string(msg + '\n', sys.stderr)
except OSError as e:
    if 'Failed to write string' in str(e):
        with open('youtube-dl.log', 'a', encoding='utf-8') as f:  # console is gone
            f.write(msg + '\n')
    else:
        raise

When it happens

Trigger: Writing progress/status output to a Windows console (tty) where WriteConsoleW fails: the handle was invalidated (window closed, console detached, piped mid-run), a console with a broken state (legacy conhost issues, redirected handle not backed by a console), or edge cases in old Windows/Python combinations. Only reachable on Windows when sys.stderr/stdout is a real console.

Common situations: User closes the console window or presses Ctrl+C during a long download; running under a terminal emulator whose console handle is flaky (older mintty/conhost wrappers); scripting youtube-dl on Windows with output redirected inconsistently; Windows 7/8 legacy console limits.

Related errors

• Playlist end must be greater than playlist start
• Not removing directory %s - this does not look like a cache

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