src.bluetooth_sig.gatt.exceptions¶

GATT exceptions for the Bluetooth SIG library.

Exceptions¶

Name	Description
`BluetoothSIGError`	Base exception for all Bluetooth SIG related errors.
`CharacteristicEncodeError`	Raised when characteristic encoding fails.
`CharacteristicError`	Base exception for characteristic-related errors.
`CharacteristicParseError`	Raised when characteristic parsing fails.
`DataEncodingError`	Exception raised when characteristic data encoding fails.
`DataParsingError`	Exception raised when characteristic data parsing fails.
`DataValidationError`	Exception raised when characteristic data validation fails.
`EnumValueError`	Exception raised when an enum value is invalid.
`IEEE11073Error`	Exception raised when IEEE 11073 format parsing fails.
`InsufficientDataError`	Exception raised when there is insufficient data for parsing.
`MissingDependencyError`	Exception raised when a required dependency is missing for multi-characteristic parsing.
`ParseFieldError`	Exception raised when a specific field fails to parse.
`ServiceCharacteristicMismatchError`	Exception raised when expected characteristics are not found in a service.
`ServiceError`	Base exception for service-related errors.
`SpecialValueDetected`	Raised when a special sentinel value is detected.
`TemplateConfigurationError`	Exception raised when a template is incorrectly configured.
`TypeMismatchError`	Exception raised when a value has an unexpected type.
`UUIDCollisionError`	Exception raised when attempting to use a UUID that already exists in SIG registry.
`UUIDRequiredError`	Exception raised when a UUID is required but not provided or invalid.
`UUIDResolutionError`	Exception raised when UUID resolution fails.
`ValueRangeError`	Exception raised when a value is outside the expected range.
`YAMLResolutionError`	Exception raised when YAML specification resolution fails.

Module Contents¶

exception src.bluetooth_sig.gatt.exceptions.BluetoothSIGError¶

Bases: Exception

Base exception for all Bluetooth SIG related errors.

exception src.bluetooth_sig.gatt.exceptions.CharacteristicEncodeError(message: str, name: str, uuid: src.bluetooth_sig.types.uuid.BluetoothUUID, value: Any, validation: src.bluetooth_sig.types.data_types.ValidationAccumulator | None = None)¶

Bases: CharacteristicError

Raised when characteristic encoding fails.

message¶: Human-readable error message

name¶: Characteristic name

uuid¶: Characteristic UUID

value¶: The value that failed to encode

validation¶: Accumulated validation results

name¶

uuid¶

validation = None¶

value¶

exception src.bluetooth_sig.gatt.exceptions.CharacteristicError¶

Bases: BluetoothSIGError

Base exception for characteristic-related errors.

exception src.bluetooth_sig.gatt.exceptions.CharacteristicParseError(message: str, name: str, uuid: src.bluetooth_sig.types.uuid.BluetoothUUID, raw_data: bytes, raw_int: int | None = None, field_errors: list[src.bluetooth_sig.types.ParseFieldError] | None = None, parse_trace: list[str] | None = None, validation: src.bluetooth_sig.types.data_types.ValidationAccumulator | None = None)¶

Bases: CharacteristicError

Raised when characteristic parsing fails.

Preserves all debugging context from parsing attempt.

message¶: Human-readable error message

name¶: Characteristic name

uuid¶: Characteristic UUID

raw_data¶: Exact bytes that failed (useful: hex dump debugging)

raw_int¶: Extracted integer value (useful: check bit patterns)

field_errors¶: Field-level errors (useful: complex multi-field characteristics)

parse_trace¶: Step-by-step execution log (useful: debug parser flow)

validation¶: Accumulated validation results (useful: see all warnings/errors)

field_errors = []¶

name¶

parse_trace = []¶

raw_data¶

raw_int = None¶

uuid¶

validation = None¶

exception src.bluetooth_sig.gatt.exceptions.DataEncodingError(characteristic: str, value: Any, reason: str)¶

Bases: CharacteristicError

Exception raised when characteristic data encoding fails.

characteristic¶

reason¶

value¶

exception src.bluetooth_sig.gatt.exceptions.DataParsingError(characteristic: str, data: bytes | bytearray, reason: str)¶

Bases: CharacteristicError

Exception raised when characteristic data parsing fails.

characteristic¶

data¶

reason¶

exception src.bluetooth_sig.gatt.exceptions.DataValidationError(field: str, value: Any, expected: str)¶

Bases: CharacteristicError

Exception raised when characteristic data validation fails.

expected¶

field¶

value¶

exception src.bluetooth_sig.gatt.exceptions.EnumValueError(field: str, value: Any, enum_class: type, valid_values: list[Any])¶

Bases: DataValidationError

Exception raised when an enum value is invalid.

enum_class¶

valid_values¶

exception src.bluetooth_sig.gatt.exceptions.IEEE11073Error(data: bytes | bytearray, format_type: str, reason: str)¶

Bases: DataParsingError

Exception raised when IEEE 11073 format parsing fails.

format_type¶

exception src.bluetooth_sig.gatt.exceptions.InsufficientDataError(characteristic: str, data: bytes | bytearray, required: int)¶

Bases: DataParsingError

Exception raised when there is insufficient data for parsing.

actual¶

required¶

exception src.bluetooth_sig.gatt.exceptions.MissingDependencyError(characteristic: str, missing_dependencies: list[str])¶

Bases: CharacteristicError

Exception raised when a required dependency is missing for multi-characteristic parsing.

characteristic¶

missing_dependencies¶

exception src.bluetooth_sig.gatt.exceptions.ParseFieldError(characteristic: str, field: str, data: bytes | bytearray, reason: str, offset: int | None = None)¶

Bases: DataParsingError

Exception raised when a specific field fails to parse.

This exception provides detailed context about which field failed, where it failed in the data, and why it failed. This enables actionable error messages and structured error reporting.

NOTE: This exception intentionally has more arguments than the standard limit to provide complete field-level diagnostic information. The additional parameters (field, offset) are essential for actionable error messages and field-level debugging.

field¶: Name of the field that failed (e.g., “temperature”, “flags”)

offset¶: Byte offset where the field starts in the raw data

expected¶: Description of what was expected

actual¶: Description of what was actually encountered

field¶

field_reason¶

offset = None¶

exception src.bluetooth_sig.gatt.exceptions.ServiceCharacteristicMismatchError(service: str, missing_characteristics: list[str])¶

Bases: ServiceError

Exception raised when expected characteristics are not found in a service.

service.

missing_characteristics¶

service¶

exception src.bluetooth_sig.gatt.exceptions.ServiceError¶

Bases: BluetoothSIGError

Base exception for service-related errors.

exception src.bluetooth_sig.gatt.exceptions.SpecialValueDetected(special_value: src.bluetooth_sig.types.SpecialValueResult, name: str, uuid: src.bluetooth_sig.types.uuid.BluetoothUUID, raw_data: bytes, raw_int: int | None = None)¶

Bases: CharacteristicError

Raised when a special sentinel value is detected.

Special values represent exceptional conditions: “value is not known”, “NaN”, “measurement not possible”, etc. These are semantically distinct from parse failures.

This exception is raised when a valid parse detects a special sentinel value (e.g., 0x8000 = “value is not known”, 0x7FFFFFFF = “NaN”). The parsing succeeded, but the result indicates an exceptional state rather than a normal value.

Most code should catch this separately from CharacteristicParseError to distinguish: - Parse failure (malformed data, wrong length, invalid format) - Special value detection (well-formed data indicating exceptional state)

special_value¶: The detected special value with meaning and raw bytes

name¶: Characteristic name

uuid¶: Characteristic UUID

raw_data¶: Raw bytes containing the special value

raw_int¶: The raw integer value (typically the sentinel value)

name¶

raw_data¶

raw_int = None¶

special_value¶

uuid¶

exception src.bluetooth_sig.gatt.exceptions.TemplateConfigurationError(template: str, configuration_issue: str)¶

Bases: CharacteristicError

Exception raised when a template is incorrectly configured.

configuration_issue¶

template¶

exception src.bluetooth_sig.gatt.exceptions.TypeMismatchError(field: str, value: Any, expected_type: type | tuple[type, Ellipsis])¶

Bases: DataValidationError

Exception raised when a value has an unexpected type.

actual_type: type¶

expected_type: type | tuple[type, Ellipsis]¶

exception src.bluetooth_sig.gatt.exceptions.UUIDCollisionError(uuid: src.bluetooth_sig.types.uuid.BluetoothUUID | str, existing_name: str, class_name: str)¶

Bases: BluetoothSIGError

Exception raised when attempting to use a UUID that already exists in SIG registry.

class_name¶

existing_name¶

uuid¶

exception src.bluetooth_sig.gatt.exceptions.UUIDRequiredError(class_name: str, entity_type: str)¶

Bases: BluetoothSIGError

Exception raised when a UUID is required but not provided or invalid.

class_name¶

entity_type¶

exception src.bluetooth_sig.gatt.exceptions.UUIDResolutionError(name: str, attempted_names: list[str] | None = None)¶

Bases: BluetoothSIGError

Exception raised when UUID resolution fails.

attempted_names = []¶

name¶

exception src.bluetooth_sig.gatt.exceptions.ValueRangeError(field: str, value: Any, min_val: Any, max_val: Any)¶

Bases: DataValidationError

Exception raised when a value is outside the expected range.

max_val¶

min_val¶

exception src.bluetooth_sig.gatt.exceptions.YAMLResolutionError(name: str, yaml_type: str)¶

Bases: BluetoothSIGError

Exception raised when YAML specification resolution fails.

name¶

yaml_type¶