> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ai-coustics.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python errors

> Exception constructors, attributes, causes and recovery for aic-sdk 3.2.0.

**Package:** `aic-sdk==3.2.0`. **Core SDK:** `0.24.0`. Source: [Python wrapper 3.2.0](https://github.com/ai-coustics/aic-sdk-py/tree/cca6f30d448c8e97bf7cfb13d6528a63de8f2c39).

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`.

<Warning>
  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.
</Warning>

The sections below describe causes, not an exhaustive list of every native call that can raise each exception. See [authentication](/models/get-started/authenticate-apps), [audio format](/reference/concepts/audio-format) and [troubleshooting](/production/troubleshooting).

## License and authorization

<a id="licenseformatinvaliderror" />

<a id="aic_sdk-LicenseFormatInvalidError" />

### LicenseFormatInvalidError

<a id="licenseformatinvaliderror-constructor" />

<a id="aic_sdk-LicenseFormatInvalidError-constructor" />

```python theme={null}
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.

<a id="licenseformatinvaliderror-message" />

<a id="aic_sdk-LicenseFormatInvalidError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="licenseexpirederror" />

<a id="aic_sdk-LicenseExpiredError" />

### LicenseExpiredError

<a id="licenseexpirederror-constructor" />

<a id="aic_sdk-LicenseExpiredError-constructor" />

```python theme={null}
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.

<a id="licenseexpirederror-message" />

<a id="aic_sdk-LicenseExpiredError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="licenseversionunsupportederror" />

<a id="aic_sdk-LicenseVersionUnsupportedError" />

### LicenseVersionUnsupportedError

<a id="licenseversionunsupportederror-constructor" />

<a id="aic_sdk-LicenseVersionUnsupportedError-constructor" />

```python theme={null}
LicenseVersionUnsupportedError(message: str)
```

**Cause:** The credential format version is unsupported by this SDK.

**Recovery:** Use a compatible released SDK and credential, or contact support.

<a id="licenseversionunsupportederror-message" />

<a id="aic_sdk-LicenseVersionUnsupportedError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="tokenunsupportederror" />

<a id="aic_sdk-TokenUnsupportedError" />

### TokenUnsupportedError

<a id="tokenunsupportederror-constructor" />

<a id="aic_sdk-TokenUnsupportedError-constructor" />

```python theme={null}
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.

<a id="tokenunsupportederror-message" />

<a id="aic_sdk-TokenUnsupportedError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="processingnotallowederror" />

<a id="aic_sdk-ProcessingNotAllowedError" />

### ProcessingNotAllowedError

<a id="processingnotallowederror-constructor" />

<a id="aic_sdk-ProcessingNotAllowedError-constructor" />

```python theme={null}
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.

<a id="processingnotallowederror-message" />

<a id="aic_sdk-ProcessingNotAllowedError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

## Model files

<a id="modelinvaliderror" />

<a id="aic_sdk-ModelInvalidError" />

### ModelInvalidError

<a id="modelinvaliderror-constructor" />

<a id="aic_sdk-ModelInvalidError-constructor" />

```python theme={null}
ModelInvalidError(message: str)
```

**Cause:** The model file is malformed or incomplete.

**Recovery:** Download the model again and verify the local file.

<a id="modelinvaliderror-message" />

<a id="aic_sdk-ModelInvalidError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="modelversionunsupportederror" />

<a id="aic_sdk-ModelVersionUnsupportedError" />

### ModelVersionUnsupportedError

<a id="modelversionunsupportederror-constructor" />

<a id="aic_sdk-ModelVersionUnsupportedError-constructor" />

```python theme={null}
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.

<a id="modelversionunsupportederror-message" />

<a id="aic_sdk-ModelVersionUnsupportedError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="modeltypeunsupportederror" />

<a id="aic_sdk-ModelTypeUnsupportedError" />

### ModelTypeUnsupportedError

<a id="modeltypeunsupportederror-constructor" />

<a id="aic_sdk-ModelTypeUnsupportedError-constructor" />

```python theme={null}
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`.

<a id="modeltypeunsupportederror-message" />

<a id="aic_sdk-ModelTypeUnsupportedError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="modeldataunalignederror" />

<a id="aic_sdk-ModelDataUnalignedError" />

### ModelDataUnalignedError

<a id="modeldataunalignederror-constructor" />

<a id="aic_sdk-ModelDataUnalignedError-constructor" />

```python theme={null}
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.

<a id="modeldataunalignederror-message" />

<a id="aic_sdk-ModelDataUnalignedError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="modeldownloaderror" />

<a id="aic_sdk-ModelDownloadError" />

### ModelDownloadError

<a id="modeldownloaderror-constructor" />

<a id="aic_sdk-ModelDownloadError-constructor" />

```python theme={null}
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.

<a id="modeldownloaderror-message" />

<a id="aic_sdk-ModelDownloadError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="modeldownloaderror-details" />

<a id="aic_sdk-ModelDownloadError-details" />

**`details: str` (read-only):** Underlying download failure details.

<a id="filesystemerror" />

<a id="aic_sdk-FileSystemError" />

### FileSystemError

<a id="filesystemerror-constructor" />

<a id="aic_sdk-FileSystemError-constructor" />

```python theme={null}
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.

<a id="filesystemerror-message" />

<a id="aic_sdk-FileSystemError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="filepathinvaliderror" />

<a id="aic_sdk-FilePathInvalidError" />

### FilePathInvalidError

<a id="filepathinvaliderror-constructor" />

<a id="aic_sdk-FilePathInvalidError-constructor" />

```python theme={null}
FilePathInvalidError(message: str)
```

**Cause:** The native file path is invalid.

**Recovery:** Use a valid path without embedded NUL characters. In aic-sdk 3.2.0 a NUL path can escape normal SDK exception conversion; validate it before calling `Model.from_file()`.

<a id="filepathinvaliderror-message" />

<a id="aic_sdk-FilePathInvalidError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

## Audio configuration and state

<a id="audioconfigunsupportederror" />

<a id="aic_sdk-AudioConfigUnsupportedError" />

### AudioConfigUnsupportedError

<a id="audioconfigunsupportederror-constructor" />

<a id="aic_sdk-AudioConfigUnsupportedError-constructor" />

```python theme={null}
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.

<a id="audioconfigunsupportederror-message" />

<a id="aic_sdk-AudioConfigUnsupportedError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="audioconfigmismatcherror" />

<a id="aic_sdk-AudioConfigMismatchError" />

### AudioConfigMismatchError

<a id="audioconfigmismatcherror-constructor" />

<a id="aic_sdk-AudioConfigMismatchError-constructor" />

```python theme={null}
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.

<a id="audioconfigmismatcherror-message" />

<a id="aic_sdk-AudioConfigMismatchError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="notinitializederror" />

<a id="aic_sdk-NotInitializedError" />

### NotInitializedError

<a id="notinitializederror-constructor" />

<a id="aic_sdk-NotInitializedError-constructor" />

```python theme={null}
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()`.

<a id="notinitializederror-message" />

<a id="aic_sdk-NotInitializedError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="parameteroutofrangeerror" />

<a id="aic_sdk-ParameterOutOfRangeError" />

### ParameterOutOfRangeError

<a id="parameteroutofrangeerror-constructor" />

<a id="aic_sdk-ParameterOutOfRangeError-constructor" />

```python theme={null}
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.

<a id="parameteroutofrangeerror-message" />

<a id="aic_sdk-ParameterOutOfRangeError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="parameterfixederror" />

<a id="aic_sdk-ParameterFixedError" />

### ParameterFixedError

<a id="parameterfixederror-constructor" />

<a id="aic_sdk-ParameterFixedError-constructor" />

```python theme={null}
ParameterFixedError(message: str)
```

**Cause:** Compatibility exception retained in the Python public surface. The 3.2.0 error mapper does not emit it.

**Recovery:** Keep it only where existing application code requires the type; current parameter validation uses `ParameterOutOfRangeError`.

<a id="parameterfixederror-message" />

<a id="aic_sdk-ParameterFixedError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

## Internal

<a id="internalerror" />

<a id="aic_sdk-InternalError" />

### InternalError

<a id="internalerror-constructor" />

<a id="aic_sdk-InternalError-constructor" />

```python theme={null}
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.

<a id="internalerror-message" />

<a id="aic_sdk-InternalError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="unknownerror" />

<a id="aic_sdk-UnknownError" />

### UnknownError

<a id="unknownerror-constructor" />

<a id="aic_sdk-UnknownError-constructor" />

```python theme={null}
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.

<a id="unknownerror-message" />

<a id="aic_sdk-UnknownError-message" />

**`message: str` (read-only):** Human-readable diagnostic text.

<a id="unknownerror-error_code" />

<a id="aic_sdk-UnknownError-error_code" />

**`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:

```python theme={null}
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](/reference/sdk/api/python/index) and [Python guide](/reference/sdk/language-bindings/python).