Skip to content

Exceptions

Exception hierarchy for dotenvmodel errors.

exceptions

Exception types for dotenvmodel.

DotEnvModelError

Bases: Exception

Base exception for all dotenvmodel errors.

All other dotenvmodel exceptions inherit from this. Catch this if you want to handle any dotenvmodel error in a single except block.

When to catch
  • When you want to handle all config errors uniformly
  • As a fallback when specific error handling isn't needed
Example 
try:
    config = AppConfig.load()
except DotEnvModelError as e:
    print(f"Configuration error: {e}")
    sys.exit(1)
See Also

ValidationError 

ValidationError(
    field_name: str,
    value: Any,
    error_msg: str,
    field_type: TypeForm[Any] | None = None,
    env_var_name: str | None = None,
)

Bases: DotEnvModelError

Raised when field validation fails.

This is the base class for specific validation errors. It's raised when a field value fails type coercion or constraint validation.

When to catch
  • When you want to handle all validation errors (coercion + constraint)
  • As a parent class for MissingFieldError, TypeCoercionError, and ConstraintViolationError

Attributes:

Name Type Description
field_name

Name of the field that failed validation
value

The value that failed validation
error_msg

Human-readable error description
field_type

The expected type (or None)
env_var_name

The environment variable name for error messages
Example 
try:
    config = Config.load_from_dict({"PORT": "abc"})
except ValidationError as e:
    print(f"Field: {e.field_name}")
    print(f"Error: {e.error_msg}")
See Also
Source code in dotenvmodel/exceptions.py 
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def __init__(
    self,
    field_name: str,
    value: Any,
    error_msg: str,
    field_type: TypeForm[Any] | None = None,
    env_var_name: str | None = None,
) -> None:
    self.field_name = field_name
    self.value = value
    self.error_msg = error_msg
    self.field_type = field_type
    self.env_var_name = env_var_name or field_name.upper()
    super().__init__(self._format_message())

field_name instance-attribute 

field_name = field_name

value instance-attribute 

value = value

error_msg instance-attribute 

error_msg = error_msg

field_type instance-attribute 

field_type = field_type

env_var_name instance-attribute 

env_var_name = env_var_name or field_name.upper()

MissingFieldError 

MissingFieldError(
    field_name: str,
    field_type: TypeForm[Any] | None = None,
    env_var_name: str | None = None,
)

Bases: ValidationError

Raised when a required field is not set.

This error occurs when a required field has no value in any source (environment variables, .env files, or dict).

When to catch
  • When you want to provide specific error messages for missing config
  • When you want to show which env vars need to be set

Attributes:

Name Type Description
field_name

Name of the missing field
env_var_name

The environment variable name that should be set
field_type

The expected type (or None)
Example 
try:
    config = AppConfig.load()
except MissingFieldError as e:
    print(f"Missing: {e.env_var_name}")
    print(f"Hint: {e}")
See Also
Source code in dotenvmodel/exceptions.py 
132
133
134
135
136
137
138
139
140
141
142
143
144
145
def __init__(
    self,
    field_name: str,
    field_type: TypeForm[Any] | None = None,
    env_var_name: str | None = None,
) -> None:
    env_name = env_var_name or field_name.upper()
    super().__init__(
        field_name=field_name,
        value=None,
        error_msg="Required field is not set",
        field_type=field_type,
        env_var_name=env_name,
    )

TypeCoercionError 

TypeCoercionError(
    field_name: str,
    value: Any,
    error_msg: str,
    field_type: TypeForm[Any] | None = None,
    env_var_name: str | None = None,
)

Bases: ValidationError

Raised when type coercion fails.

This error occurs when a string value from the environment cannot be converted to the field's target type (e.g., "abc" to int).

When to catch
  • When you want to show helpful messages for invalid config values
  • When you want to identify which env var has a formatting issue

Attributes:

Name Type Description
field_name

Name of the field that failed coercion
value

The string value that couldn't be coerced
error_msg

Description of why coercion failed
field_type

The target type
env_var_name

The environment variable name
Example 
try:
    config = Config.load_from_dict({"PORT": "abc"})
except TypeCoercionError as e:
    print(f"{e.env_var_name}: {e.error_msg}")
    # PORT: invalid literal for int() with base 10: 'abc'
See Also
Source code in dotenvmodel/exceptions.py 
77
78
79
80
81
82
83
84
85
86
87
88
89
90
def __init__(
    self,
    field_name: str,
    value: Any,
    error_msg: str,
    field_type: TypeForm[Any] | None = None,
    env_var_name: str | None = None,
) -> None:
    self.field_name = field_name
    self.value = value
    self.error_msg = error_msg
    self.field_type = field_type
    self.env_var_name = env_var_name or field_name.upper()
    super().__init__(self._format_message())

ConstraintViolationError 

ConstraintViolationError(
    field_name: str,
    value: Any,
    constraint: str,
    error_msg: str,
    env_var_name: str | None = None,
)

Bases: ValidationError

Raised when a validation constraint is violated.

This error occurs when a value passes type coercion but fails a validation constraint (e.g., port > 65535, string too short).

When to catch
  • When you want to show which constraint was violated
  • When you want to help users fix invalid config values

Attributes:

Name Type Description
field_name

Name of the field that violated a constraint
value

The value that violated the constraint
constraint

The constraint that was violated (e.g., "ge=1")
error_msg

Human-readable constraint error
env_var_name

The environment variable name
Example 
try:
    config = Config.load_from_dict({"PORT": "99999"})
except ConstraintViolationError as e:
    print(f"{e.field_name}: {e.constraint} - {e.error_msg}")
    # port: le=65535 - Value must be less than or equal to 65535
See Also
Source code in dotenvmodel/exceptions.py 
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
def __init__(
    self,
    field_name: str,
    value: Any,
    constraint: str,
    error_msg: str,
    env_var_name: str | None = None,
) -> None:
    self.constraint = constraint
    super().__init__(
        field_name=field_name,
        value=value,
        error_msg=error_msg,
        env_var_name=env_var_name,
    )

constraint instance-attribute 

constraint = constraint

MultipleValidationErrors 

MultipleValidationErrors(errors: list[ValidationError])

Bases: DotEnvModelError

Raised when multiple validation errors occur simultaneously.

When loading a config with multiple invalid fields, all errors are collected and raised together in this exception rather than failing on the first error.

When to catch
  • When you want to show all config errors at once (better UX)
  • When you want to identify all missing/invalid fields in one pass

Attributes:

Name Type Description
errors

List of ValidationError instances (one per failed field)
Example 
try:
    config = AppConfig.load()
except MultipleValidationErrors as e:
    for error in e.errors:
        print(f"  - {error.field_name}: {error.error_msg}")
See Also
Source code in dotenvmodel/exceptions.py 
285
286
287
def __init__(self, errors: list[ValidationError]) -> None:
    self.errors = errors
    super().__init__(self._format_message())

errors instance-attribute 

errors = errors