ytdl-org/youtube-dl · error · ValueError

Playlist end must be greater than playlist start

Error message

Playlist end must be greater than playlist start

What it means

Raised on Windows by youtube-dl's file-locking helper: the Win32 LockFileEx call (via msvcrt.get_osfhandle) failed, and ctypes.FormatError() supplies the OS error text. It occurs while acquiring the lock youtube-dl uses for its .part/download coordination and cache files (locked_file context manager). The %r message is the Windows error string, e.g. a sharing violation or access-denied description.

Source

Thrown at youtube_dl/__init__.py:206

        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)
    else:
        date = DateRange(opts.dateafter, opts.datebefore)

View on GitHub (pinned to 956b8c5855)

Solutions

1. Ensure only one youtube-dl instance writes the same output file at a time (distinct --output templates per job, or a queue).
2. Read the embedded FormatError text: 'being used by another process' → find the other holder; 'Access is denied' → fix directory/file permissions.
3. Add the download directory to antivirus exclusions (or accept the race) and retry.
4. For network shares, download to a local temp dir and move afterwards — LockFileEx over SMB is unreliable.

Example fix

# before
with locked_file('video.mp4.part', 'a') as f:  # may fail if locked elsewhere
    ...

# after
import random, time
for attempt in range(3):
    try:
        with locked_file('video.mp4.part', 'a') as f:
            ...
        break
    except OSError:
        time.sleep(2 ** attempt + random.random())

import os

def can_lock(path):
    d = os.path.dirname(os.path.abspath(path)) or '.'
    return os.access(d, os.W_OK) and os.path.exists(d)

from youtube_dl.utils import locked_file
import time, random
for attempt in range(3):
    try:
        with locked_file(path, 'a') as f:
            f.write(b'')
        break
    except OSError as e:
        if 'Locking file failed' in str(e) and attempt < 2:
            time.sleep((2 ** attempt) + random.random())
            continue
        raise  # persistent holder (AV, other process) — surface it

When it happens

Trigger: Two youtube-dl processes downloading to the same output file simultaneously; antivirus/backup software holding the file; the file being open in another program (player, torrent client); insufficient permissions on the directory; locking a file on a network share (SMB) that does not support byte-range locks.

Common situations: Cron jobs or launchers that overlap runs; Windows Defender scanning .part files at the exact moment of locking; downloading to a NAS/SMB path where LockFileEx semantics differ; running without write permission to the output directory.

Related errors

• Not removing directory %s - this does not look like a cache
• Playlist start must be positive
• %s said: %s
• message (dynamic from service error response, error.get('mes

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