Enum Error 

pub enum Error {
    Runtime {
        context: String,
        source: JoinError,
    },
    IO {
        operation: String,
        path: Option<PathBuf>,
        source: Error,
    },
    Archive {
        file: String,
        source: ArchiveError,
    },
    Http {
        url: String,
        context: String,
        source: Error,
    },
    Timeout {
        operation: String,
        duration: Duration,
    },
    Json {
        context: String,
        source: Error,
    },
    Database {
        operation: String,
        source: Box<Error>,
    },
    NoBinaryRelease {
        binary: String,
        platform: Platform,
        architecture: Architecture,
    },
    BinaryNotFound {
        binary: String,
        path: PathBuf,
    },
    CommandFailed {
        command: String,
        exit_code: i32,
        stderr: String,
    },
    VideoFetch {
        url: String,
        reason: String,
    },
    VideoMissingField {
        video_id: String,
        field: String,
    },
    FormatNotAvailable {
        video_id: String,
        format_type: FormatType,
        available_formats: Vec<String>,
    },
    FormatNoUrl {
        video_id: String,
        format_id: String,
    },
    FormatIncompatible {
        format_id: String,
        reason: String,
    },
    NoThumbnail {
        video_id: String,
    },
    SubtitleNotAvailable {
        video_id: String,
        language: String,
    },
    UrlExpired,
    PathValidation {
        path: PathBuf,
        reason: String,
    },
    UrlValidation {
        url: String,
        reason: String,
    },
    DownloadFailed {
        download_id: u64,
        reason: String,
    },
    DownloadCancelled {
        download_id: u64,
    },
    InvalidPartialRange {
        reason: String,
    },
    LiveStreamUnavailable {
        url: String,
        live_status: String,
        reason: String,
    },
    HlsParsing {
        url: String,
        context: String,
    },
    LiveRecording {
        url: String,
        reason: String,
    },
    LiveStreaming {
        url: String,
        reason: String,
    },
    Metadata {
        operation: String,
        path: PathBuf,
        reason: String,
    },
    CacheMiss {
        key: String,
    },
    CacheExpired {
        key: String,
    },
    AmbiguousCacheBackend {
        count: usize,
    },
    ChecksumMismatch {
        path: PathBuf,
        expected: String,
        actual: String,
    },
    InvalidHeader {
        header: String,
        reason: String,
    },
    UnexpectedStatus {
        status: u16,
        url: String,
    },
    Unknown(String),
}

The possible errors that can occur in the yt-dlp library.

Each error variant provides detailed context about what went wrong, including the operation being performed and any relevant parameters.

Variants

Runtime

An async task failed to complete.

This typically indicates a panic in a spawned tokio task or a cancellation.

Fields

context: String

source: JoinError

IO

A file system operation failed.

Includes the operation being performed and the path involved.

Fields

operation: String

path: Option<PathBuf>

source: Error

Archive

An archive extraction operation failed.

This occurs when extracting yt-dlp or ffmpeg archives.

Fields

file: String

source: ArchiveError

Http

An HTTP request failed.

Includes the URL being accessed and the operation context.

Fields

url: String

context: String

source: Error

Timeout

A network timeout occurred.

Indicates the operation and duration that was exceeded.

Fields

operation: String

duration: Duration

Json

JSON parsing or serialization failed.

Includes the context of what was being parsed/serialized.

Fields

context: String

source: Error

Database

Database operation failed (redb backend).

Includes the specific operation that failed.

Fields

operation: String

source: Box<Error>

NoBinaryRelease

No GitHub release asset found for the current platform.

This occurs when trying to download yt-dlp or ffmpeg binaries.

Fields

binary: String

platform: Platform

architecture: Architecture

BinaryNotFound

The required binary was not found after installation.

This indicates an installation issue or corrupted download.

Fields

binary: String

path: PathBuf

CommandFailed

Command execution failed.

Includes the command, exit status, and stderr output.

Fields

command: String

exit_code: i32

stderr: String

VideoFetch

Failed to fetch video information from YouTube.

Includes the URL and reason for failure.

Fields

url: String

reason: String

VideoMissingField

Video information is missing expected data.

This occurs when YouTube’s API returns incomplete data.

Fields

video_id: String

field: String

FormatNotAvailable

The requested format is not available.

Includes the format type and available alternatives.

Fields

video_id: String

format_type: FormatType

available_formats: Vec<String>

FormatNoUrl

The format has no URL available for download.

This can occur with DRM-protected or geo-restricted content.

Fields

video_id: String

format_id: String

FormatIncompatible

The format is incompatible with the requested operation.

For example, trying to extract audio from a video-only format.

Fields

format_id: String

reason: String

NoThumbnail

No thumbnail is available for the video.

Fields

video_id: String

SubtitleNotAvailable

No subtitles are available for the requested language.

Fields

video_id: String

language: String

UrlExpired

The URL has expired and needs to be refreshed.

PathValidation

Path validation failed due to security concerns.

This prevents path traversal and other security issues.

Fields

path: PathBuf

reason: String

UrlValidation

URL validation failed.

This ensures only valid YouTube URLs are processed.

Fields

url: String

reason: String

DownloadFailed

Download operation failed.

Includes the download ID and reason for failure.

Fields

download_id: u64

reason: String

DownloadCancelled

Download was cancelled by user or system.

Fields

download_id: u64

InvalidPartialRange

A partial download range is invalid or the container format does not support seeking.

Fields

reason: String

LiveStreamUnavailable

The video is not currently a live stream.

Fields

url: String

live_status: String

reason: String

HlsParsing

Failed to parse an HLS manifest.

Fields

url: String

context: String

LiveRecording

A live recording operation failed.

Fields

url: String

reason: String

LiveStreaming

A live streaming operation failed.

Fields

url: String

reason: String

Metadata

A metadata tagging operation failed.

This occurs when reading or writing audio/video tags (ID3, MP4, lofty).

Fields

operation: String

path: PathBuf

reason: String

CacheMiss

The requested item was not found in the cache.

Fields

key: String

CacheExpired

The cached item has expired.

Fields

key: String

AmbiguousCacheBackend

Multiple persistent cache backends are compiled in but none was selected.

Set CacheConfig::persistent_backend explicitly when more than one of cache-json, cache-redb, or cache-redis features are active.

Fields

count: usize

ChecksumMismatch

A checksum verification failed after downloading.

Fields

path: PathBuf

expected: String

actual: String

InvalidHeader

An HTTP header value was invalid.

Fields

header: String

reason: String

UnexpectedStatus

An HTTP response status was unexpected.

Fields

status: u16

url: String

Unknown(String)

An unexpected error occurred that doesn’t fit other categories.

This should be used sparingly and ideally replaced with more specific variants.

Implementations

impl Error

pub fn io(operation: impl Into<String>, source: Error) -> Self

Create an IO error with operation context.

Arguments

• operation - Description of the operation that failed
• source - The underlying IO error

Returns

An Error::IO variant with the provided context

pub fn io_with_path( operation: impl Into<String>, path: impl Into<PathBuf>, source: Error, ) -> Self

Create an IO error with operation and path context.

Arguments

• operation - Description of the operation that failed
• path - The file path involved in the operation
• source - The underlying IO error

Returns

An Error::IO variant with the provided context and path

pub fn http( url: impl Into<String>, context: impl Into<String>, source: Error, ) -> Self

Create an HTTP error with URL context.

Arguments

• url - The URL that was being accessed
• context - Additional context about the operation
• source - The underlying reqwest error

Returns

An Error::Http variant with the provided context

pub fn json(context: impl Into<String>, source: Error) -> Self

Create a JSON parsing error with context.

Arguments

• context - Description of what was being parsed/serialized
• source - The underlying serde_json error

Returns

An Error::Json variant with the provided context

pub fn database(operation: impl Into<String>, source: impl Into<Error>) -> Self

Create a database error with operation context (redb).

Arguments

• operation - Description of the database operation that failed
• source - The underlying redb error

Returns

An Error::Database variant with the provided context

pub fn runtime(context: impl Into<String>, source: JoinError) -> Self

Create a runtime error with context.

Arguments

• context - Description of the task that failed
• source - The underlying tokio JoinError

Returns

An Error::Runtime variant with the provided context

pub fn video_fetch(url: impl Into<String>, reason: impl Into<String>) -> Self

Create a video fetch error.

Arguments

• url - The URL that failed to fetch
• reason - The reason for the fetch failure

Returns

An Error::VideoFetch variant with the provided details

pub fn path_validation( path: impl Into<PathBuf>, reason: impl Into<String>, ) -> Self

Create a path validation error.

Arguments

• path - The path that failed validation
• reason - The reason for validation failure

Returns

An Error::PathValidation variant with the provided details

pub fn url_validation(url: impl Into<String>, reason: impl Into<String>) -> Self

Create a URL validation error.

Arguments

• url - The URL that failed validation
• reason - The reason for validation failure

Returns

An Error::UrlValidation variant with the provided details

pub fn invalid_partial_range(reason: impl Into<String>) -> Self

Create an invalid partial range error.

Arguments

• reason - Description of why the partial range is invalid

Returns

An Error::InvalidPartialRange variant with the provided reason

pub fn download_failed(download_id: u64, reason: impl Into<String>) -> Self

Create a download failed error.

Arguments

• download_id - The ID of the download that failed
• reason - The reason for the download failure

Returns

An Error::DownloadFailed variant with the provided details

pub fn live_unavailable( url: impl Into<String>, live_status: impl Into<String>, reason: impl Into<String>, ) -> Self

Create a live stream unavailable error.

Arguments

• url - The URL of the video
• live_status - The current live status of the video
• reason - Why the stream is not available

Returns

An Error::LiveStreamUnavailable variant with the provided details

pub fn hls_parsing(url: impl Into<String>, context: impl Into<String>) -> Self

Create an HLS parsing error.

Arguments

• url - The URL of the manifest that failed to parse
• context - Description of the parsing failure

Returns

An Error::HlsParsing variant with the provided details

pub fn live_recording(url: impl Into<String>, reason: impl Into<String>) -> Self

Create a live recording error.

Arguments

• url - The URL of the live stream
• reason - Why the recording failed

Returns

An Error::LiveRecording variant with the provided details

pub fn live_streaming(url: impl Into<String>, reason: impl Into<String>) -> Self

Create a live streaming error.

Arguments

• url - The URL of the live stream
• reason - Why the streaming failed

Returns

An Error::LiveStreaming variant with the provided details

pub fn live_segment_fetch_failed(url: &str, status: StatusCode) -> Self

Create an error for a failed live segment fetch.

Arguments

• url - The URL of the live segment
• status - The HTTP status code returned

Returns

An Error::LiveStreaming variant with the provided details

pub fn metadata( operation: impl Into<String>, path: impl Into<PathBuf>, reason: impl Into<String>, ) -> Self

Create a metadata error with operation and path context.

Arguments

• operation - Description of the metadata operation (e.g. “read MP4 tags”)
• path - The file path involved
• reason - The reason for the failure

Returns

An Error::Metadata variant with the provided context

pub fn cache_miss(key: impl Into<String>) -> Self

Create a cache miss error.

Arguments

• key - The cache key that was not found

Returns

An Error::CacheMiss variant

pub fn cache_expired(key: impl Into<String>) -> Self

Create a cache expired error.

Arguments

• key - The cache key that expired

Returns

An Error::CacheExpired variant

pub fn ambiguous_cache_backend(count: usize) -> Self

Create an ambiguous cache backend error.

Arguments

• count - The number of persistent backends compiled in

Returns

An Error::AmbiguousCacheBackend variant

Trait Implementations

impl Debug for Error

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Error

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for Error

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<Error> for Error

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

Available on crate feature cache-redb only.

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(err: Error) -> Self

Converts to this type from the input type.

impl From<JoinError> for Error

fn from(err: JoinError) -> Self

Converts to this type from the input type.

impl From<ZipError> for Error

fn from(err: ZipError) -> Self

Converts to this type from the input type.