Skip to main content
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.

​
Installation or native library loading fails

Applies to: Native 0.24.0; WebAssembly 0.23.0 has a separate initialization sequence. 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, then install its pinned package in a fresh environment. For Python, run this in the environment that runs your application:
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. 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:
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. 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 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.

​
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. See 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 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 and your LiveKit or Pipecat 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 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.

​
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 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 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. 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. 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 or your support agreement.