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

# How to troubleshoot an integration

> Find the failing stage, apply a targeted recovery and verify that audio processing is active.

Start with the first failing operation: installation, model loading, processor creation, initialization, processing or shutdown. Record the binding version, core SDK version, model ID and sanitized error. Keep credentials, authorization headers and private audio out of diagnostics.

## Versions and error references

The recipes target these releases. "Native 0.24.0" includes Python package 3.2.0. Use your binding's error reference; exception names differ across languages.

| Binding         | Package or distribution            | Core   | Complete error reference                                                |
| :-------------- | :--------------------------------- | :----- | :---------------------------------------------------------------------- |
| **Python**      | `aic-sdk` 3.2.0                    | 0.24.0 | [Python exceptions](/reference/sdk/api/python/errors)                   |
| **Node.js**     | `@ai-coustics/aic-sdk` 0.24.0      | 0.24.0 | [Node.js errors](/reference/sdk/api/node/errors)                        |
| **C**           | SDK 0.24.0                         | 0.24.0 | [C status codes](/reference/sdk/api/c/errors-and-types)                 |
| **C++**         | Wrapper 0.24.0                     | 0.24.0 | [C++ results and errors](/reference/sdk/api/cpp/results-and-errors)     |
| **Rust**        | `aic-sdk` 0.24.0                   | 0.24.0 | [Rust errors and features](/reference/sdk/api/rust/errors-and-features) |
| **WebAssembly** | `@ai-coustics/aic-sdk-wasm` 0.23.0 | 0.23.0 | [WebAssembly errors](/reference/sdk/api/wasm/errors)                    |

| First failing stage                        | Recovery recipe                                                                                                                                                            |
| :----------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Package import or native loading**       | [Installation](#installation-or-native-library-loading-fails)                                                                                                              |
| **Model download or creation**             | [Model loading](#model-download-or-loading-fails)                                                                                                                          |
| **Credential validation or refresh**       | [Credentials](#credentials-are-missing-invalid-or-expired)                                                                                                                 |
| **Authorization or terminated session**    | [Disallowed processing](#processing-becomes-disallowed)                                                                                                                    |
| **Initialization or audio length**         | [Audio configuration](#audio-configuration-or-frame-size-is-rejected)                                                                                                      |
| **Unexpected audio or predictions**        | [Output](#output-is-silent-distorted-or-unexpectedly-unchanged), [VAD](#voice-activity-detection-behaves-incorrectly) or [analysis](#analysis-fails-or-repeats-old-scores) |
| **Missed audio deadlines or queue growth** | [Performance](#latency-or-cpu-use-increases)                                                                                                                               |
| **No collector observations**              | [Metrics](#metrics-are-missing)                                                                                                                                            |

## Installation or native library loading fails

**Applies to:** Native 0.24.0; WebAssembly 0.23.0 has a separate [initialization sequence](/reference/sdk/api/wasm/initialization).

**Diagnostic:** Record the package-manager, import or loader error and your runtime, OS and architecture. With Rust's `runtime-linking` feature, `DynamicLoadingError::OpenLibrary` means the library could not be opened; automatic loading instead panics on failure.

Check platform support in your [language guide](/reference/sdk/language-bindings), then install its pinned package in a fresh environment.

For Python, run this in the environment that runs your application:

```bash theme={null}
python -c 'import importlib.metadata, platform; import aic_sdk as aic; print("binding:", importlib.metadata.version("aic-sdk")); print("core:", aic.get_sdk_version()); print("platform:", platform.system(), platform.machine())'
```

For C and C++, check the include path, linked library and runtime loader path against the build example. Rebuild for the target architecture.

**Verify:** Repeat the import or build in the deployment environment. Confirm the reported core SDK version before retrying audio.

## Model download or loading fails

**Applies to:** Native 0.24.0; use the WebAssembly error reference for its 0.23.0 model-byte loader.

**Diagnostic:** Python reports `ModelDownloadError`, `FileSystemError`, `ModelInvalidError` or `ModelVersionUnsupportedError` depending on the failing stage. In C/C++, native status `103` is a filesystem failure and `101` is an incompatible model format. Preserve the error category; redact private paths or URLs from details.

Check the exact model ID in the [model catalog](/reference/sdk/models). Confirm it is supported by the installed core SDK; old model IDs are not aliases for current models.

For a download failure, check connectivity, output-directory permissions and available disk space. For a local load failure, check the actual path and file contents. Redownload into a new directory instead of overwriting a model used by running sessions. A `ModelVersionUnsupportedError` requires a compatible SDK/model combination.

**Verify:** Repeat the download or load, then run the language quickstart from the deployment path. Confirm model creation, initialization and processing succeed.

## Credentials are missing, invalid or expired

**Applies to:** Native 0.24.0. Browser clients using WebAssembly 0.23.0 receive JWTs from their backend.

**Diagnostic:** The native quickstart guard emits `Set AIC_SDK_LICENSE to your SDK key, then retry.` for missing or placeholder credentials. Python native failures include `LicenseFormatInvalidError`, `LicenseExpiredError` and `TokenUnsupportedError`; C/C++ use status `50`, `52` and `53`, respectively. Record the category, never the supplied credential.

`AIC_SDK_LICENSE` must be available to the running service, not just your interactive shell. Check presence without printing its value:

```bash theme={null}
python -c 'import os; print("AIC_SDK_LICENSE is set:", bool(os.environ.get("AIC_SDK_LICENSE")))'
```

Pass the complete SDK key to your server-side processor, including its signed contents. For JWT integrations, obtain a fresh token from your authenticated backend, check expiry and system time and follow the [refresh procedure](/models/get-started/authenticate-apps#refresh-before-the-token-expires).

`LicenseFormatInvalidError` during construction means local credential validation failed before that session's online activation. During token refresh, the same error indicates a malformed replacement; the previous token remains installed. Check that the complete key was copied without truncation or added characters; do not edit its encoded contents. Test the key or token mode your application uses.

`TokenUnsupportedError` during refresh means the original or replacement credential is not a JWT. A processor created with a plain SDK key cannot switch to JWT authentication in place. Use the [authentication guide](/models/get-started/authenticate-apps) for the supported key/token flow.

**Verify:** Retry with a valid credential and check processing through the session lifecycle; construction can precede backend activation.

## Processing becomes disallowed

**Applies to:** Native 0.24.0; WebAssembly 0.23.0 throws a JavaScript `Error` rather than a Python exception.

**Diagnostic:** Python `ProcessingNotAllowedError`, C/C++ status `6` or Rust `AicError::ProcessingNotAllowed`. The native `usage.disallowed` metric measures disallowed audio duration.

Check authorization, required usage reporting and whether your application called `terminate_session()`. Termination can finish after that call returns.

* **Refresh a JWT** through its context when the session can continue; allow backend reactivation and observe errors during recovery.
* **Replace a revoked or invalid SDK key** and create a new processor using the replacement.
* **Create a new instance after termination.** A terminated session cannot be resumed by resetting stream state.
* **Check outbound connectivity** for online operation. Disabling SDK error reporting does not remove authorization requirements.

Catch the error and apply your fallback or stop policy. Python returns no enhanced array when processing raises.

**Verify:** Process the controlled fixture, confirm valid output and check that disallowed usage stops increasing for the recovered session. See [deployment failure policy](/production/deployment#set-a-capacity-and-failure-policy).

## Audio configuration or frame size is rejected

**Applies to:** Native 0.24.0. Use WebAssembly 0.23.0's own initialization and array signatures.

**Diagnostic:** Python `NotInitializedError`, `AudioConfigUnsupportedError` or `AudioConfigMismatchError`; corresponding C/C++ statuses are `3`, `4` and `5`. Record sample rate, mono sample count, dtype and fixed/variable mode, without recording audio. The Python/Node.js quickstart rejects stereo input with `Export input.wav as mono, 16 kHz, 16-bit PCM WAV, then retry.`

`NotInitializedError` means the processor needs initialization. `AudioConfigMismatchError` indicates that a call does not match the configured audio shape or block size.

Use decoded mono `float32` samples at the configured rate and block size. Exclude file headers and count samples, not bytes: each `float32` sample occupies four bytes.

Use `ProcessorConfig.optimal(model)` when the source matches the model's optimal rate, or explicitly configure the actual source rate. Handle the final partial block using the method shown in your [quickstart](/models/get-started/sdk-quickstart). See [audio format](/reference/concepts/audio-format) for variable blocks and channel handling.

**Verify:** Resubmit a valid block, then rerun the quickstart. Check output shape, duration and playback speed.

## Output is silent, distorted or unexpectedly unchanged

**Applies to:** Native 0.24.0 and WebAssembly 0.23.0, using each binding's output contract.

**Diagnostic:** Compare input/output sample counts and rate, finite-value checks and peak amplitude. Read the processor bypass and enhancement-level settings. Audio quality problems may produce no SDK error.

Check input amplitude, finite values, channel conversion and sample rate, then inspect the model, enhancement strength and bypass setting.

Account for startup delay and final buffered output when evaluating short recordings. Use [latency guidance](/reference/concepts/latency) to align input and output. For a framework integration, verify that the filter loaded and is active rather than assuming an audible call proves enhancement.

**Verify:** Compare input and output from the same recording: check durations and listen at matched playback settings.

## Voice activity detection behaves incorrectly

**Applies to:** Native 0.24.0 and WebAssembly 0.23.0 dedicated VAD APIs.

**Diagnostic:** Record the model ID, frame order, latest speech decision and parameter values on a controlled fixture. Python `ModelTypeUnsupportedError` or native status `105` indicates an incompatible model type. Incorrect timing or stale predictions can occur without an exception.

Check that you use a supported dedicated VAD model and feed it the signal required by your integration. Reusing processor state across callers or processing frames out of order can invalidate the result.

Follow the signal flow in the [VAD guide](/models/voice-activity-detection/vad) and your [LiveKit](/models/get-started/livekit-quickstart) or [Pipecat](/models/get-started/pipecat-quickstart) guide. Tune detection thresholds and speech/silence timing using representative recordings, including quiet speech and competing speakers.

**Verify:** Compare detected speech intervals against labeled recordings and verify turn behavior in the full agent pipeline.

## Analysis fails or repeats old scores

**Applies to:** Native 0.24.0; Node.js combines collection and analysis on `Analyzer`. WebAssembly 0.23.0 has its own analysis API.

**Diagnostic:** Python `NotInitializedError` or C/C++ status `3` from buffering means the collector is uninitialized. Record buffered sample counts and analysis times. Repeated scores alone do not indicate a failure.

Initialize collection before buffering. Analysis reads the latest retained window; repeated calls without new audio can inspect the same data. A reset makes analysis use zeros until collection applies the reset. Buffer fresh normalized mono samples under the configured block contract before expecting new observations. Use the [Python analysis reference](/reference/sdk/api/python/analysis) or your binding's analysis reference for collector ownership and window behavior.

**Verify:** Buffer a known recording and check the analysis result and errors. Confirm new audio reached collection; scores need not change on every call. For complete files, follow [Tyto analysis](/models/audio-insight/batch-call-analysis).

## Latency or CPU use increases

**Applies to:** Native 0.24.0. Measure WebAssembly 0.23.0 in its actual browser/runtime; native OTel metrics are unavailable there.

**Diagnostic:** Record wall-clock processing percentiles, queue depth, stream count and the frame budget (`1000 * samples / sample_rate` ms). Native metrics include `experimental.processor.realtime_violations`, a count of calls that exceeded the frame budget, and `experimental.processor.process_duration_max`, a duration in ns. No SDK exception uniquely identifies overload.

Separate SDK output delay from wall-clock processing time, buffering and downstream service latency. Check CPU throttling, growing queues, stream count and accidental model loading or network work on the audio thread.

Run the [performance procedure](/reference/concepts/performance) under deployment resource limits. Reduce admitted concurrency or change model/configuration only after measuring the trade-off.

**Verify:** Repeat the workload after one change. Confirm processing percentiles fit the frame budget at target concurrency and queue depth stays bounded.

## Metrics are missing

**Applies to:** Native core 0.24.0 enhancement processors and VADs. WebAssembly 0.23.0 does not export SDK OTel metrics.

Native analyzers and file analysis do not export optional OpenTelemetry metrics, even with `AIC_SDK_OTEL_ENABLE=1`. Use the [analysis result APIs](/reference/sdk/api/python/analysis) instead. SDK authorization and usage reporting still apply.

**Diagnostic:** After processing and an export interval, look for service `aic-sdk`, meter `aic_usage` and `usage.processed` at the collector. Record enabled state, export interval and a sanitized endpoint. Exclude authentication headers and identifying attributes.

Follow [OpenTelemetry troubleshooting](/models/get-started/opentelemetry#troubleshooting). Check that metrics are enabled before instance creation, a native build is in use, audio is actually processed and the collector accepts OTLP/HTTP Protobuf. Keep the session alive long enough to export.

**Verify:** Restart the session with the corrected configuration and rerun the [local collector example](/models/get-started/opentelemetry#verify-with-a-local-collector). Find `service.name=aic-sdk`, `model.id` and increasing `usage.processed` after additional audio in the same session.

## Prepare a support report

Include the failing stage, a minimal reproduction, package/core/model versions, OS/architecture, sanitized error, audio configuration and fixture result. Add session timing and a correlation ID where your data policy allows.

Remove credentials, customer identifiers and private audio. Use the support route in the [developer platform](https://developers.ai-coustics.com/) or your support agreement.