Enum SubXError 

pub enum SubXError {
    Io(Error),
    Config {
        message: String,
    },
    SubtitleFormat {
        format: String,
        message: String,
    },
    AiService(String),
    Api {
        message: String,
        source: ApiErrorSource,
    },
    AudioProcessing {
        message: String,
    },
    FileMatching {
        message: String,
    },
    FileAlreadyExists(String),
    FileNotFound(String),
    InvalidFileName(String),
    FileOperationFailed(String),
    CommandExecution(String),
    NoInputSpecified,
    InvalidPath(PathBuf),
    PathNotFound(PathBuf),
    DirectoryReadError {
        path: PathBuf,
        source: Error,
    },
    InvalidSyncConfiguration,
    UnsupportedFileType(String),
    OutputModeUnsupported {
        command: String,
    },
    Other(Error),
}

Represents all possible errors in the SubX application.

Each variant provides specific context to facilitate debugging and user-friendly reporting.

Examples

use subx_core::error::{SubXError, SubXResult};

fn example() -> SubXResult<()> {
    Err(SubXError::SubtitleFormat {
        format: "SRT".to_string(),
        message: "Invalid timestamp format".to_string(),
    })
}

Exit Codes

Each error variant maps to a stable process exit code (1–6). That mapping is a property of running the subx-cli binary and lives in that binary’s SubXErrorExt::exit_code extension trait (rendered terminal prose likewise); this enum itself carries only the machine-readable contract — Self::category, Self::machine_code and Self::hint — which library consumers can call without importing anything.

Variants

Io(Error)

I/O operation failed during file system access.

This variant wraps std::io::Error and provides context about file operations that failed.

Common Causes

• Permission issues
• Insufficient disk space
• Network filesystem errors

Config

Configuration error due to invalid or missing settings.

Contains a human-readable message describing the issue.

Fields

message: String

Description of the configuration error

SubtitleFormat

Subtitle format error indicating invalid timestamps or structure.

Provides the subtitle format and detailed message.

Fields

format: String

The subtitle format that caused the error (e.g., “SRT”, “ASS”)

message: String

Detailed error message describing the issue

AiService(String)

AI service encountered an error.

Captures the raw error message from the AI provider.

Api

API request error with specified source.

Represents errors that occur during API requests, providing both the error message and the source of the API error.

Fields

message: String

Error message from the API

source: ApiErrorSource

Source of the API error

AudioProcessing

Audio processing error during analysis or format conversion.

Provides a message describing the audio processing failure.

Fields

message: String

Description of the audio processing error

FileMatching

Error during file matching or discovery.

Contains details about path resolution or pattern matching failures.

Fields

message: String

Description of the file matching error

FileAlreadyExists(String)

Indicates that a file operation failed because the target exists.

FileNotFound(String)

Indicates that the specified file was not found.

InvalidFileName(String)

Invalid file name encountered.

FileOperationFailed(String)

Generic file operation failure with message.

CommandExecution(String)

Generic command execution error.

NoInputSpecified

No input path was specified for the operation.

InvalidPath(PathBuf)

The provided path is invalid or malformed.

PathNotFound(PathBuf)

The specified path does not exist on the filesystem.

DirectoryReadError

Unable to read the specified directory.

Fields

path: PathBuf

The directory path that could not be read

source: Error

The underlying I/O error

InvalidSyncConfiguration

Invalid synchronization configuration: please specify video and subtitle files, or use -i parameter for batch processing.

UnsupportedFileType(String)

Unsupported file type encountered.

OutputModeUnsupported

The active output mode (e.g. --output json) is incompatible with the requested subcommand.

Currently emitted by generate-completion, whose stdout is by design a shell-completion script and cannot be wrapped in the JSON envelope contract.

Only the subx-cli binary ever constructs this variant — no code under src/core/ or src/services/ produces it. It nevertheless stays in the core enum so category() and machine_code() keep their wildcard-free exhaustive matches (a new variant must be mapped, not absorbed by a catch-all). The deliberate asymmetry below — category() is the generic "command_execution" while machine_code() is the more specific "E_OUTPUT_MODE_UNSUPPORTED" — is spec-locked.

Fields

command: String

The subcommand that rejected the output mode (e.g. "generate-completion").

Other(Error)

Catch-all error variant wrapping any other failure.

Implementations

impl SubXError

pub fn config<S>(message: S) -> SubXError

where S: Into<String>,

Create a configuration error with the given message.

Examples

let err = SubXError::config("invalid setting");
assert_eq!(err.to_string(), "Configuration error: invalid setting");

pub fn subtitle_format<S1, S2>(format: S1, message: S2) -> SubXError

where S1: Into<String>, S2: Into<String>,

Create a subtitle format error for the given format and message.

Examples

let err = SubXError::subtitle_format("SRT", "invalid timestamp");
assert!(err.to_string().contains("SRT"));

pub fn audio_processing<S>(message: S) -> SubXError

where S: Into<String>,

Create an audio processing error with the given message.

Examples

let err = SubXError::audio_processing("decode failed");
assert_eq!(err.to_string(), "Audio processing error: decode failed");

pub fn ai_service<S>(message: S) -> SubXError

where S: Into<String>,

Create an AI service error with the given message.

Examples

let err = SubXError::ai_service("network failure");
assert_eq!(err.to_string(), "AI service error: network failure");

pub fn file_matching<S>(message: S) -> SubXError

where S: Into<String>,

Create a file matching error with the given message.

Examples

let err = SubXError::file_matching("not found");
assert_eq!(err.to_string(), "File matching error: not found");

pub fn parallel_processing(msg: String) -> SubXError

Create a parallel processing error with the given message.

pub fn task_execution_failed(task_id: String, reason: String) -> SubXError

Create a task execution failure error with task ID and reason.

pub fn worker_pool_exhausted() -> SubXError

Create a worker pool exhausted error.

pub fn task_timeout(task_id: String, duration: Duration) -> SubXError

Create a task timeout error with task ID and duration.

pub fn dialogue_detection_failed<S>(msg: S) -> SubXError

where S: Into<String>,

Create a dialogue detection failure error with the given message.

pub fn invalid_audio_format<S>(format: S) -> SubXError

where S: Into<String>,

Create an invalid audio format error for the given format.

pub fn dialogue_segment_invalid<S>(reason: S) -> SubXError

where S: Into<String>,

Create an invalid dialogue segment error with the given reason.

pub fn category(&self) -> &'static str

Stable snake_case machine-readable category for the JSON error envelope. The mapping is closed and exhaustive (no wildcard arm) so the compiler enforces updates whenever a new variant is added.

This mapping is locked by the error-handling capability spec.

pub fn machine_code(&self) -> &'static str

Stable upper-snake-case machine code prefixed with E_. Mirrors Self::category one-to-one and is similarly closed against the addition of new variants.

pub fn hint(&self) -> Option<&'static str>

Short user-facing remediation hint, or None when none applies.

This is a separate, structured surface from the prose hints already baked into the binary’s SubXErrorExt::user_friendly_message (src/cli/error_ext.rs); JSON callers receive it under error.hint.

The returned text is written for the subx-cli terminal and names its binary and flags. Library consumers SHALL treat the return value as an availability signal — branch on Some/None and render their own localized copy — rather than as display copy. Rewriting the prose is not a breaking change; changing which variants return Some is: that set is the stable part of the contract.

impl SubXError

Helper functions for Whisper API and audio processing related errors.

pub fn whisper_api<T>(message: T) -> SubXError

where T: Into<String>,

Create a Whisper API error.

Arguments

• message - The error message describing the Whisper API failure

Returns

A new SubXError::Api variant with Whisper as the source

pub fn audio_extraction<T>(message: T) -> SubXError

where T: Into<String>,

Create an audio extraction/transcoding error.

Arguments

• message - The error message describing the audio processing failure

Returns

A new SubXError::AudioProcessing variant

Trait Implementations

impl Debug for SubXError

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

Formats the value using the given formatter.

impl Display for SubXError

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

Formats the value using the given formatter.

impl Error for SubXError

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<Box<dyn Error>> for SubXError

fn from(err: Box<dyn Error>) -> SubXError

Converts to this type from the input type.

impl From<ConfigError> for SubXError

fn from(err: ConfigError) -> SubXError

Converts to this type from the input type.

impl From<Error> for SubXError

fn from(source: Error) -> SubXError

Converts to this type from the input type.

impl From<Error> for SubXError

fn from(source: Error) -> SubXError

Converts to this type from the input type.

impl From<Error> for SubXError

fn from(err: Error) -> SubXError

Converts to this type from the input type.

impl From<Error> for SubXError

fn from(err: Error) -> SubXError

Converts to this type from the input type.

impl From<Error> for SubXError

fn from(err: Error) -> SubXError

Converts to this type from the input type.

impl From<Error> for SubXError

fn from(err: Error) -> SubXError

Converts to this type from the input type.

impl SubXErrorExt for SubXError

fn exit_code(&self) -> i32

Return the corresponding exit code for this error variant.

fn user_friendly_message(&self) -> String

Return a user-friendly error message with suggested remedies.