Python errors

Package: aic-sdk==3.4.0. Core SDK: 0.26.0. Every SDK exception below subclasses Exception directly. There is no shared SDK base exception. Catch the specific errors you can recover from. Native failures from model loading, constructors, initialization, processing, parameter control, token updates and analysis are mapped to these classes. Every class accepts message: str and exposes a read-only message: str property. ModelDownloadError and UnknownError require one additional constructor argument, shown below. The inherited args, str() and traceback behavior comes from Python’s Exception. Python argument conversion can instead raise TypeError for an incorrect NumPy dtype or dimension, or OverflowError for integers outside the native unsigned range. A noncontiguous one-dimensional float32 view is accepted and normalized by the wrapper. Wrong block length is a separate SDK error. Async methods can raise conversion errors when called and SDK errors when awaited. Background download task failure can raise RuntimeError.

A Python processing exception returns no output array. The wrapper discards its local output on an SDK error, even if the underlying C processor writes fallback samples. Choose and implement your application fallback explicitly.

The sections below describe causes, not an exhaustive list of every native call that can raise each exception. See authentication, audio format and troubleshooting.

License and authorization

`LicenseFormatInvalidError`

LicenseFormatInvalidError(message: str)

Cause: The SDK key or JWT is malformed, empty or contains a NUL character. Recovery: Check that you copied the complete credential without extra characters. Read it from your approved secret source; do not print it. message: str (read-only): Human-readable diagnostic text.

`LicenseExpiredError`

LicenseExpiredError(message: str)

Cause: The credential has expired. Recovery: Renew it. For a session originally created with a JWT, update the bearer token before expiry. Recreate the session when token replacement is unsupported. message: str (read-only): Human-readable diagnostic text.

`LicenseVersionUnsupportedError`

LicenseVersionUnsupportedError(message: str)

Cause: The credential format version is unsupported by this SDK. Recovery: Use a compatible released SDK and credential, or contact support. message: str (read-only): Human-readable diagnostic text.

`TokenUnsupportedError`

TokenUnsupportedError(message: str)

Cause: Token replacement is only supported when the original credential and replacement are both JWTs. Recovery: Use a JWT from initial session creation if rotation is required. The rejected replacement is not installed; recreate the session when changing credential type. message: str (read-only): Human-readable diagnostic text.

`ProcessingNotAllowedError`

ProcessingNotAllowedError(message: str)

Cause: Authorization or usage reporting failed, or the session was terminated. This can occur after successful initialization. Recovery: Check the credential and required network access. Keep handling this error in the processing loop. A terminated session requires a new processor, detector or analyzer; a reset does not reopen it. message: str (read-only): Human-readable diagnostic text.

Model files

`ModelInvalidError`

ModelInvalidError(message: str)

Cause: The model file is malformed or incomplete. Recovery: Download the model again and verify the local file. message: str (read-only): Human-readable diagnostic text.

`ModelVersionUnsupportedError`

ModelVersionUnsupportedError(message: str)

Cause: The model file format is incompatible with the installed core SDK. Recovery: Use Model.download() with the installed SDK to select compatible data. Compare get_compatible_model_version() when diagnosing a manually supplied file. message: str (read-only): Human-readable diagnostic text.

`ModelTypeUnsupportedError`

ModelTypeUnsupportedError(message: str)

Cause: The model type does not match the operation. Recovery: Use an enhancement model for Processor, a dedicated VAD model for Vad and a Tyto analysis model for analyzer_pair or FileAnalyzer. message: str (read-only): Human-readable diagnostic text.

`ModelDataUnalignedError`

ModelDataUnalignedError(message: str)

Cause: Native model data does not satisfy the required 64-byte alignment. Recovery: Python exposes file loading rather than raw buffer loading. Use Model.from_file(); report this error with package and platform details if it occurs through that path. message: str (read-only): Human-readable diagnostic text.

`ModelDownloadError`

ModelDownloadError(message: str, details: str)

Cause: Manifest retrieval, model selection, download, verification or writing the destination failed. Recovery: Inspect details, check the model ID, network access and destination permissions, then retry the download. message: str (read-only): Human-readable diagnostic text. details: str (read-only): Underlying download failure details.

`FileSystemError`

FileSystemError(message: str)

Cause: The model file cannot be opened or read. Recovery: Check that the path exists, is a model file and is readable. message: str (read-only): Human-readable diagnostic text.

`FilePathInvalidError`

FilePathInvalidError(message: str)

Cause: The native file path is invalid. Recovery: Use a valid path without embedded NUL characters. In aic-sdk 3.4.0 a NUL path can escape normal SDK exception conversion; validate it before calling Model.from_file(). message: str (read-only): Human-readable diagnostic text.

Audio configuration and state

`AudioConfigUnsupportedError`

AudioConfigUnsupportedError(message: str)

Cause: The native sample rate or block configuration is unsupported. FileAnalyzer also rejects sample_rate=0 and step_samples=0. Recovery: Start with ProcessorConfig.optimal(model), then initialize. Native input rates are 8,000–192,000 Hz; use a positive block size and a configuration supported by the model. message: str (read-only): Human-readable diagnostic text.

`AudioConfigMismatchError`

AudioConfigMismatchError(message: str)

Cause: The number of samples differs from the initialized fixed size or exceeds the maximum variable size. Recovery: Use exactly config.block_size mono samples, or a block of up to that size with variable_block_size=True. A wrong dtype or dimension raises Python TypeError instead. message: str (read-only): Human-readable diagnostic text.

`NotInitializedError`

NotInitializedError(message: str)

Cause: Processing or buffering was attempted before initialization. Recovery: Pass config to the processor or detector constructor, or call initialize/initialize_async. Initialize the Collector before buffer(). message: str (read-only): Human-readable diagnostic text.

`ParameterOutOfRangeError`

ParameterOutOfRangeError(message: str)

Cause: A parameter value lies outside its supported range. Recovery: Use the bounds on ProcessorParameter or VadParameter. Read the current value with get_parameter(); do not infer model-specific defaults. message: str (read-only): Human-readable diagnostic text.

`ParameterFixedError`

ParameterFixedError(message: str)

Cause: Compatibility exception retained in the Python public surface. The 3.4.0 error mapper does not emit it. Recovery: Keep it only where existing application code requires the type; current parameter validation uses ParameterOutOfRangeError. message: str (read-only): Human-readable diagnostic text.

Internal

`InternalError`

InternalError(message: str)

Cause: A native internal operation failed. A NUL-containing OtelConfig.session_id also maps to this error during processor or detector construction. Recovery: First check the supplied session ID. For other failures, retain package/core versions and a minimal reproduction and contact support; omit credentials. message: str (read-only): Human-readable diagnostic text.

`UnknownError`

UnknownError(message: str, error_code: int)

Cause: The native SDK returned an error code not recognized by this wrapper. Recovery: Record error_code and package/core versions, then report a minimal reproduction without credentials. message: str (read-only): Human-readable diagnostic text. error_code: int (read-only): Signed 32-bit native error code.

Handling an error

This example exercises a local file error without a model download or SDK credential:

from pathlib import Path
from tempfile import TemporaryDirectory
import aic_sdk as aic

with TemporaryDirectory() as directory:
    try:
        aic.Model.from_file(Path(directory) / "missing.aicmodel")
    except aic.FileSystemError as error:
        print(type(error).__name__)  # FileSystemError

See the Python API index and Python guide.

SDK

API reference

Upgrades

LiveKit

AI tools

Historical migrations

License and authorization

`LicenseFormatInvalidError`

`LicenseExpiredError`

`LicenseVersionUnsupportedError`

`TokenUnsupportedError`

`ProcessingNotAllowedError`

Model files

`ModelInvalidError`

`ModelVersionUnsupportedError`

`ModelTypeUnsupportedError`

`ModelDataUnalignedError`

`ModelDownloadError`

`FileSystemError`

`FilePathInvalidError`

Audio configuration and state

`AudioConfigUnsupportedError`

`AudioConfigMismatchError`

`NotInitializedError`

`ParameterOutOfRangeError`

`ParameterFixedError`

Internal

`InternalError`

`UnknownError`

Handling an error

​License and authorization

​LicenseFormatInvalidError

​LicenseExpiredError

​LicenseVersionUnsupportedError

​TokenUnsupportedError

​ProcessingNotAllowedError

​Model files

​ModelInvalidError

​ModelVersionUnsupportedError

​ModelTypeUnsupportedError

​ModelDataUnalignedError

​ModelDownloadError

​FileSystemError

​FilePathInvalidError

​Audio configuration and state

​AudioConfigUnsupportedError

​AudioConfigMismatchError

​NotInitializedError

​ParameterOutOfRangeError

​ParameterFixedError

​Internal

​InternalError

​UnknownError

​Handling an error

License and authorization

`LicenseFormatInvalidError`

`LicenseExpiredError`

`LicenseVersionUnsupportedError`

`TokenUnsupportedError`

`ProcessingNotAllowedError`

Model files

`ModelInvalidError`

`ModelVersionUnsupportedError`

`ModelTypeUnsupportedError`

`ModelDataUnalignedError`

`ModelDownloadError`

`FileSystemError`

`FilePathInvalidError`

Audio configuration and state

`AudioConfigUnsupportedError`

`AudioConfigMismatchError`

`NotInitializedError`

`ParameterOutOfRangeError`

`ParameterFixedError`

Internal

`InternalError`

`UnknownError`

Handling an error