Config Exceptions

Configuration failures surface through a dedicated hierarchy rooted at KstlibError. Importing from kstlib.config.exceptions keeps the error handling consistent across loaders, exporters, and the CLI.

Exception Hierarchy

KstlibError
└── ConfigError
    ├── ConfigFileNotFoundError    # Config file not found
    ├── ConfigFormatError          # Invalid YAML/JSON format
    ├── ConfigCircularIncludeError # Recursive include detected
    ├── ConfigIncludeDepthError    # Include depth exceeded (max 10)
    └── ConfigNotLoadedError       # Config not initialized

Quick overview

• KstlibError groups every library-specific exception so callers can guard large sections of code with a single except.

• ConfigError narrows that scope to configuration-specific faults; downstream modules inherit from it when they depend on config state.

• ConfigFileNotFoundError extends FileNotFoundError to include the missing path in the message.

• ConfigFormatError captures parsing issues (unsupported extension, invalid YAML/JSON, strict mode violations).

• ConfigCircularIncludeError prevents recursive include directives.

• ConfigIncludeDepthError prevents deeply nested includes (max depth: 10) to protect against resource exhaustion attacks or misconfiguration.

• ConfigNotLoadedError is raised by helpers such as require_config() when the global configuration has not been initialised yet.

Usage patterns

Guarding config loads

from kstlib.config import load_config
from kstlib.config.exceptions import ConfigFileNotFoundError, ConfigFormatError

try:
    config = load_config("kstlib.conf.yml")
except ConfigFileNotFoundError:
    raise SystemExit("Config missing; run kstlib config init")
except ConfigFormatError as error:
    raise SystemExit(f"Config invalid: {error}")

Ensuring configuration is present

from kstlib.config import require_config
from kstlib.config.exceptions import ConfigNotLoadedError

try:
    config = require_config()
except ConfigNotLoadedError:
    config = load_default_profile()

Module reference

Exception hierarchy for kstlib.

All kstlib exceptions inherit from KstlibError, allowing users to catch all kstlib-specific errors with a single except clause.

Example

try:

config = load_config()

except KstlibError as e:

# Catch any kstlib error print(f”Error: {e}”)

exception kstlib.config.exceptions.ConfigCircularIncludeError

Bases: ConfigError, ValueError

Circular include detected in configuration files.

Raised when an include chain creates a cycle (A includes B, B includes A).

exception kstlib.config.exceptions.ConfigError

Bases: KstlibError

Base exception for configuration-related errors.

All config module exceptions inherit from this class.

exception kstlib.config.exceptions.ConfigFileNotFoundError

Bases: ConfigError, FileNotFoundError

Configuration file not found at specified location.

Raised when attempting to load a config file that doesn’t exist.

exception kstlib.config.exceptions.ConfigFormatError

Bases: ConfigError, ValueError

Invalid configuration format or unsupported file type.

Raised when: - File extension is not supported (.xml, etc.) - Format mismatch in strict mode (YAML including JSON) - Invalid content that cannot be parsed

exception kstlib.config.exceptions.ConfigIncludeDepthError

Bases: ConfigError, ValueError

Include depth limit exceeded.

Raised when config includes are nested too deeply, which may indicate a misconfiguration or an attempt to exhaust resources.

exception kstlib.config.exceptions.ConfigNotLoadedError

Bases: ConfigError, RuntimeError

Configuration not loaded yet.

Raised by require_config() when attempting to access config before it has been loaded via get_config() or load_config().

exception kstlib.config.exceptions.ConfigSopsError

Bases: ConfigError

SOPS decryption failed for a configuration file.

Raised when SOPS binary fails to decrypt a .sops.* file.

exception kstlib.config.exceptions.ConfigSopsNotAvailableError

Bases: ConfigSopsError

SOPS binary not installed or not found in PATH.

Raised when attempting to decrypt a .sops.* file but the SOPS binary is not available. Install from https://github.com/getsops/sops

exception kstlib.config.exceptions.KstlibError

Bases: Exception

Base exception for all kstlib errors.

All kstlib-specific exceptions inherit from this class, allowing for easy catching of any kstlib error.