Exceptions

Exception Hierarchy

Varlord provides a unified exception hierarchy for error handling. All custom exceptions inherit from VarlordError.

Base Exception

class varlord.exceptions.VarlordError(message, code=None)

Bases: Exception

Base exception for all Varlord errors.

All exceptions raised by Varlord inherit from this class, allowing users to: - Catch all Varlord errors with except VarlordError - Identify error types programmatically using the code attribute

message

Human-readable error message

code

Machine-readable error code (e.g., “CONFIG_LOAD_FAILED”)

Example

>>> try:
...     cfg.load()
... except VarlordError as e:
...     print(f"Error {e.code}: {e.message}")

__init__(message, code=None)

Initialize VarlordError.

Parameters:

• message (str) – Human-readable error message

• code (str | None) – Machine-readable error code (defaults to class name)

__repr__()

Return string representation.

__str__()

Return user-friendly string representation.

Configuration Exceptions

class varlord.exceptions.ConfigError(message, code=None)

Bases: VarlordError

Base exception for configuration-related errors.

class varlord.exceptions.ConfigLoadError(message, source_name=None, code='CONFIG_LOAD_FAILED')

Bases: ConfigError

Raised when configuration loading fails.

This can occur when: - A source fails to load (e.g., file not found, permission denied) - Type conversion fails (e.g., invalid int value) - Validation fails (e.g., missing required field)

source_name

Name of the source that failed (if applicable)

__init__(message, source_name=None, code='CONFIG_LOAD_FAILED')

Initialize ConfigLoadError.

Parameters:

• message (str) – Human-readable error message

• source_name (str | None) – Name of the source that failed (e.g., “yaml”, “env”)

• code (str) – Machine-readable error code

class varlord.exceptions.SourceLoadError(message, source_name=None, code='CONFIG_LOAD_FAILED')

Bases: ConfigLoadError

Raised when a configuration source fails to load.

This is a subclass of ConfigLoadError for backward compatibility.

Validation Exceptions

class varlord.exceptions.ValidationError(message, field_name=None, code='VALIDATION_FAILED')

Bases: ConfigError

Raised when configuration validation fails.

This can occur when: - Required fields are missing - Field values fail custom validation - Model definition is invalid

__init__(message, field_name=None, code='VALIDATION_FAILED')

Initialize ValidationError.

Parameters:

• message (str) – Human-readable error message

• field_name (str | None) – Name of the field that failed validation (if applicable)

• code (str) – Machine-readable error code

class varlord.exceptions.RequiredFieldError(message, field_name=None)

Bases: ValidationError

Raised when a required field is missing.

field_name

Name of the missing required field

__init__(message, field_name=None)

Initialize RequiredFieldError.

Parameters:

• message (str) – Human-readable error message

• field_name (str | None) – Name of the missing required field

class varlord.exceptions.ModelDefinitionError(message)

Bases: ValidationError

Raised when model definition is invalid.

This can occur when: - Fields are missing required metadata - Field types are unsupported - Field names conflict with reserved names

__init__(message)

Initialize ModelDefinitionError.

Parameters:

message (str) – Human-readable error message

class varlord.exceptions.ConversionError(message, field_name=None, field_type=None, value=None)

Bases: ConfigError

Raised when type conversion fails.

This can occur when: - String value cannot be converted to target type - Invalid boolean value (not “true”/”false”/”1”/”0”) - Invalid numeric value (not an integer/float)

__init__(message, field_name=None, field_type=None, value=None)

Initialize ConversionError.

Parameters:

• message (str) – Human-readable error message

• field_name (str | None) – Name of the field that failed conversion

• field_type (str | None) – Target type name (e.g., “int”, “bool”)

• value (str | None) – The value that failed to convert

class varlord.exceptions.ResolverError(message, code='RESOLVER_FAILED')

Bases: ConfigError

Raised when source resolution fails.

This can occur when: - Priority policy is invalid - Source merge fails - Circular dependencies detected

__init__(message, code='RESOLVER_FAILED')

Initialize ResolverError.

Parameters:

• message (str) – Human-readable error message

• code (str) – Machine-readable error code

Usage Examples

Catching All Varlord Exceptions

from varlord import Config, VarlordError

cfg = Config(model=MyConfig, sources=[...])
try:
    config = cfg.load()
except VarlordError as e:
    print(f"Configuration error {e.code}: {e.message}")

Catching Specific Exceptions

from varlord import Config, ConfigLoadError, ValidationError

cfg = Config(model=MyConfig, sources=[...])
try:
    config = cfg.load()
except ConfigLoadError as e:
    print(f"Failed to load from {e.source_name}: {e.message}")
except ValidationError as e:
    print(f"Field {e.field_name} failed validation: {e.message}")

Error Codes

All exceptions have an error code for programmatic handling:

• CONFIG_LOAD_FAILED - Configuration loading failed

• SOURCE_LOAD_FAILED - Source failed to load

• VALIDATION_FAILED - Validation failed

• MISSING_REQUIRED_FIELD - Required field is missing

• INVALID_MODEL_DEFINITION - Model definition is invalid

• TYPE_CONVERSION_FAILED - Type conversion failed

• RESOLVER_FAILED - Source resolution failed

Note

Always catch VarlordError instead of generic Exception to distinguish configuration errors from other exceptions.

See also

Config

Main configuration class

varlord.sources

Configuration sources