Exceptions Reference

# Data catalog and dataset exceptions
from kedro.io import (
    DatasetError,
    DatasetNotFoundError,
    DatasetAlreadyExistsError,
    VersionNotFoundError,
    VersionAlreadyExistsError
)

# Pipeline exceptions
from kedro.pipeline import (
    PipelineError,
    OutputNotUniqueError,
    ConfirmNotUniqueError,
    CircularDependencyError
)

# Configuration exceptions
from kedro.config import (
    BadConfigException,
    MissingConfigException
)

# Framework exceptions
from kedro.framework.session import KedroSessionError
from kedro.framework.context import KedroContextError

class DatasetError(Exception):
    """Base exception for dataset errors."""

class DatasetNotFoundError(DatasetError):
    """Raised when trying to use a non-existing dataset."""

class DatasetAlreadyExistsError(DatasetError):
    """Raised when trying to add a dataset that already exists."""

class VersionNotFoundError(DatasetError):
    """
    Raised when trying to load a non-existing version of a dataset.

    This exception is raised by AbstractVersionedDataset implementations
    when no load versions are available for the dataset.

    Common causes:
    - Attempting to load a versioned dataset with no saved versions
    - Specifying a version that doesn't exist in the version directory
    - Misconfigured load_versions in DataCatalog

    Example:
    >>> catalog = DataCatalog(load_versions={"my_data": "2024-01-01T00.00.00.000Z"})
    >>> # Raises VersionNotFoundError if that version doesn't exist
    >>> data = catalog.load("my_data")
    """

class VersionAlreadyExistsError(DatasetError):
    """
    Raised when attempting to save data with a version that already exists.

    This exception is raised by DataCatalog when attempting to add a dataset
    with a save version that conflicts with the save version already set for
    the catalog.

    Common causes:
    - Trying to save with an existing version timestamp
    - Version conflict in concurrent pipeline runs
    - Manual version specification that already exists

    Solutions:
    - Use generate_timestamp() to create unique versions
    - Enable automatic versioning instead of manual versions
    - Clear or archive old versions if needed

    Example:
    >>> catalog = DataCatalog(save_version="2024-01-01T00.00.00.000Z")
    >>> # Raises VersionAlreadyExistsError if trying to set conflicting save_version
    """

class BadConfigException(Exception):
    """Raised when a configuration file cannot be loaded."""

class MissingConfigException(Exception):
    """Raised when no configuration files found."""

class PipelineError(Exception):
    """
    Base exception for pipeline construction and validation errors.

    Raised when a pipeline is not adapted and integrated appropriately.

    Common causes:
    - Invalid pipeline structure
    - Incompatible pipeline operations
    - Failed pipeline composition

    Example:
    >>> # Raised when pipeline operation is invalid
    >>> pipeline1 + invalid_object  # Not a Pipeline
    """

class OutputNotUniqueError(Exception):
    """
    Raised when multiple nodes produce outputs with the same name.

    This error is detected during pipeline construction to prevent
    data conflicts where multiple nodes attempt to write to the
    same dataset.

    Solutions:
    - Rename outputs to make them unique
    - Use namespacing to separate conflicting outputs
    - Ensure each dataset has only one producer node

    Example:
    >>> node1 = node(func1, "input", "output")
    >>> node2 = node(func2, "input", "output")  # Same output name!
    >>> pipeline([node1, node2])  # Raises OutputNotUniqueError
    """

class ConfirmNotUniqueError(Exception):
    """
    Raised when multiple nodes attempt to confirm the same dataset.

    This error occurs when two or more nodes in a pipeline specify
    the same dataset in their 'confirms' parameter.

    Solutions:
    - Ensure only one node confirms each dataset
    - Review node confirmation requirements
    - Use different confirmation datasets for different nodes

    Example:
    >>> node1 = node(func1, "input1", "output1", confirms="my_data")
    >>> node2 = node(func2, "input2", "output2", confirms="my_data")
    >>> pipeline([node1, node2])  # Raises ConfirmNotUniqueError
    """

class CircularDependencyError(Exception):
    """
    Raised when nodes have circular dependencies preventing topological ordering.

    This error is detected when the pipeline cannot be executed because
    nodes depend on each other in a circular manner (A depends on B,
    B depends on C, C depends on A).

    Solutions:
    - Review node input/output relationships
    - Break circular dependencies by refactoring functions
    - Ensure data flows in one direction through pipeline

    Example:
    >>> node1 = node(func1, "data_a", "data_b")
    >>> node2 = node(func2, "data_b", "data_c")
    >>> node3 = node(func3, "data_c", "data_a")  # Creates cycle!
    >>> pipeline([node1, node2, node3])  # Raises CircularDependencyError
    """

class KedroSessionError(Exception):
    """
    Raised for session-related errors.

    Common causes:
    - Attempting to create session without proper project setup
    - Session already active when creating new session
    - Invalid environment specified
    - Missing project metadata or configuration

    Example:
    >>> from kedro.framework.session import KedroSession
    >>> # Raises KedroSessionError if not in a Kedro project directory
    >>> session = KedroSession.create()
    """

class KedroContextError(Exception):
    """
    Raised for context-related errors.

    Common causes:
    - Invalid catalog configuration
    - Missing required configuration files
    - Failed to load project context
    - Invalid project structure or settings

    Solutions:
    - Verify project structure with required conf/ directory
    - Check catalog.yml and parameters.yml syntax
    - Ensure settings.py contains valid configuration
    - Verify KEDRO_ENV environment variable if set

    Example:
    >>> from kedro.framework.session import KedroSession
    >>> with KedroSession.create() as session:
    >>>     # Raises KedroContextError if catalog config is invalid
    >>>     context = session.load_context()
    """

class KedroCliError(Exception):
    """
    Raised for CLI-related errors.

    Common causes:
    - Invalid CLI command or arguments
    - Failed to execute command
    - Missing required command parameters
    - Plugin loading failures

    Solutions:
    - Verify command syntax: kedro --help
    - Check plugin installation if using custom commands
    - Ensure project is properly initialized
    - Validate command-specific requirements

    Example:
    >>> # Raises KedroCliError if command is invalid or fails
    >>> # kedro run --pipeline non_existent_pipeline
    """

class TaskError(Exception):
    """Raised for task execution failures."""

class KedroDeprecationWarning(DeprecationWarning):
    """Warning for deprecated Kedro features."""

class KedroPythonVersionWarning(UserWarning):
    """Warning for Python version incompatibilities."""