Implementation:Iterative Dvc Exceptions

Knowledge Sources	Iterative_Dvc
Domains	Error_Handling, Core
Last Updated	2026-02-10 10:00 GMT

Overview

Custom exception hierarchy providing structured error handling across the entire DVC codebase.

Description

The dvc.exceptions module defines DvcException as the base exception class and over 15 specialized subclasses that represent specific error conditions encountered during DVC operations. The hierarchy covers repository errors (NotDvcRepoError), file and output errors (OutputDuplicationError, OutputNotFoundError, PathMissingError), pipeline errors (CyclicGraphError, StagePathAsOutputError), remote and download errors (DownloadError, UploadError), and data integrity issues (CheckoutError, CollectCacheError). Each exception carries structured context (file paths, stage names, remote URLs) to produce clear, actionable error messages for both CLI users and API consumers.

Usage

These exceptions are raised throughout the DVC codebase and are caught at command handler boundaries to produce user-friendly error messages. When building extensions or integrations that call DVC internals, catch DvcException as the general base class or specific subclasses for fine-grained error handling.

Code Reference

Source Location

• Repository: Iterative_Dvc
• File: dvc/exceptions.py
• Lines: 1-371

Signature

class DvcException(Exception):
    """Base exception for all DVC errors.

    Attributes:
        msg (str): Human-readable error message.
    """

    def __init__(self, msg: str, *args, **kwargs):
        ...

class OutputDuplicationError(DvcException):
    """Raised when multiple stages produce the same output path."""

    def __init__(self, output: str, stages: list):
        ...

class OutputNotFoundError(DvcException):
    """Raised when a referenced output does not exist in any stage."""

    def __init__(self, output: str, repo=None):
        ...

class NotDvcRepoError(DvcException):
    """Raised when a DVC command is run outside a DVC repository."""

    def __init__(self, root: Optional[str] = None):
        ...

class PathMissingError(DvcException):
    """Raised when a requested path does not exist in the repository or remote storage."""

    def __init__(self, path: str, repo: str, output_only: bool = False):
        ...

class CyclicGraphError(DvcException):
    """Raised when the pipeline dependency graph contains a cycle."""

class StagePathAsOutputError(DvcException):
    """Raised when a stage file path overlaps with a tracked output."""

    def __init__(self, stage: str, output: str):
        ...

class DownloadError(DvcException):
    """Raised when downloading files from remote storage fails."""

    def __init__(self, count: int):
        ...

class UploadError(DvcException):
    """Raised when uploading files to remote storage fails."""

    def __init__(self, count: int):
        ...

class CheckoutError(DvcException):
    """Raised when checking out cached files to the workspace fails."""

    def __init__(self, target_infos: list, stats: Optional[dict] = None):
        ...

class CollectCacheError(DvcException):
    """Raised when collecting cache information fails due to missing data."""

class ConfirmRemoveError(DvcException):
    """Raised when user declines to confirm removal of existing outputs."""

class InitError(DvcException):
    """Raised when DVC repository initialization fails."""

class ReproductionError(DvcException):
    """Raised when pipeline reproduction fails for a specific stage."""

    def __init__(self, name: str):
        ...

class FileMissingError(DvcException):
    """Raised when a required file is missing from the workspace."""

    def __init__(self, path: str):
        ...

class InvalidArgumentError(DvcException):
    """Raised when invalid arguments are provided to a DVC command or API call."""

Import

from dvc.exceptions import (
    DvcException,
    OutputDuplicationError,
    OutputNotFoundError,
    NotDvcRepoError,
    PathMissingError,
    CyclicGraphError,
    DownloadError,
    UploadError,
    CheckoutError,
)

I/O Contract

Exception Categories

Category	Exceptions	Description
Repository Errors	NotDvcRepoError, InitError	Errors related to DVC repository detection and initialization
Output Errors	OutputDuplicationError, OutputNotFoundError, StagePathAsOutputError	Conflicts or missing references in pipeline outputs
Path Errors	PathMissingError, FileMissingError	Requested files or paths not found in the workspace or remote storage
Pipeline Errors	CyclicGraphError, ReproductionError	Structural or execution problems in the pipeline DAG
Transfer Errors	DownloadError, UploadError	Failures during remote file transfer operations
Cache Errors	CheckoutError, CollectCacheError	Problems restoring cached files to the workspace
User Interaction Errors	ConfirmRemoveError	User declined a required confirmation prompt
Argument Errors	InvalidArgumentError	Invalid CLI or API arguments provided

Exception Attributes

Exception	Key Attributes	Description
DvcException	msg (str)	Base message describing the error
OutputDuplicationError	output (str), stages (list)	The duplicated output path and the conflicting stages
PathMissingError	path (str), repo (str), output_only (bool)	The missing path, the repository, and whether only outputs were searched
DownloadError	count (int)	Number of files that failed to download
UploadError	count (int)	Number of files that failed to upload
CheckoutError	target_infos (list), stats (dict)	Targets that failed checkout and statistics about the failure
ReproductionError	name (str)	Name of the stage that failed reproduction

Usage Examples

Catching Repository Errors

from dvc.exceptions import NotDvcRepoError
from dvc.repo import Repo

try:
    repo = Repo("/path/to/directory")
except NotDvcRepoError:
    print("The specified directory is not a DVC repository.")
    print("Run 'dvc init' to initialize it.")

Handling Missing Paths

from dvc.exceptions import PathMissingError

try:
    url = dvc.api.get_url("data/nonexistent.csv", repo="https://github.com/example/project")
except PathMissingError as exc:
    print(f"File '{exc.path}' not found in repository '{exc.repo}'.")
    if exc.output_only:
        print("The file exists in the repo but is not a DVC-tracked output.")

Handling Pipeline Errors

from dvc.exceptions import CyclicGraphError, ReproductionError

try:
    repo.reproduce()
except CyclicGraphError:
    print("Pipeline contains a dependency cycle. Review dvc.yaml for circular references.")
except ReproductionError as exc:
    print(f"Stage '{exc.name}' failed during reproduction.")

General DVC Exception Handling

from dvc.exceptions import DvcException

try:
    # Perform any DVC operation
    repo.push()
except DvcException as exc:
    # Catch all DVC-specific errors
    print(f"DVC operation failed: {exc.msg}")
    raise

Handling Transfer Errors

from dvc.exceptions import DownloadError, UploadError

try:
    repo.pull()
except DownloadError as exc:
    print(f"Failed to download {exc.count} file(s) from remote storage.")

try:
    repo.push()
except UploadError as exc:
    print(f"Failed to upload {exc.count} file(s) to remote storage.")

Related Pages

• Environment:Iterative_Dvc_Python_Runtime