{"record":{"id":"2934bd8495e1e72c","repo":"stride3d/stride","slug":"failed-to-create-an-instance-of-the-celt-encoder-decoder","errorCode":null,"errorMessage":"Failed to create an instance of the celt encoder/decoder.","messagePattern":"Failed to create an instance of the celt encoder/decoder\\.","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Audio/Native/Celt.cs","lineNumber":45,"sourceCode":"            NativeInvoke.PreLoad();\n        }\n\n        /// <summary>\n        /// Initialize the Celt encoder/decoder\n        /// </summary>\n        /// <param name=\"sampleRate\">Required sample rate</param>\n        /// <param name=\"bufferSize\">Required buffer size</param>\n        /// <param name=\"channels\">Required channels</param>\n        /// <param name=\"decoderOnly\">If we desire only to decode set this to true</param>\n        public Celt(int sampleRate, int bufferSize, int channels, bool decoderOnly)\n        {\n            SampleRate = sampleRate;\n            BufferSize = bufferSize;\n            Channels = channels;\n            celtPtr = xnCeltCreate(sampleRate, bufferSize, channels, decoderOnly);\n            if (celtPtr == IntPtr.Zero)\n            {\n                throw new Exception(\"Failed to create an instance of the celt encoder/decoder.\");\n            }\n        }\n\n        /// <summary>\n        /// Dispose the Celt encoder/decoder\n        /// Do not call Encode or Decode after disposal!\n        /// </summary>\n        public void Dispose()\n        {\n            if (celtPtr != IntPtr.Zero)\n            {\n                xnCeltDestroy(celtPtr);\n                celtPtr = IntPtr.Zero;\n            }\n        }\n\n        /// <summary>\n        /// Decodes compressed celt data into PCM 16 bit shorts","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Audio/Native/Celt.cs#L27-L63","documentation":"Thrown from the desktop/Xenko-path Celt constructor when xnCeltCreate returns a NULL pointer, meaning the native library failed to instantiate the combined Celt encoder/decoder for the requested parameters. No Celt encode/decode can proceed without this handle.","triggerScenarios":"Constructing Celt with sampleRate/bufferSize/channels the native xnCeltCreate cannot honor, or when the native celt library is missing, mismatched, or fails to allocate.","commonSituations":"Missing native dependency on the deployment machine; passing hardware-derived sample rates that the codec doesn't support; memory pressure in long-running audio applications.","solutions":["Use codec-supported parameters (e.g. 48000 Hz sample rate, standard frame size, 1-2 channels).","Verify the native celt binary ships with and matches your build/platform.","Catch the failure at startup and fall back to uncompressed audio or disable audio features.","Update Stride/native dependencies to a matched version set."],"exampleFix":"// before\nvar celt = new Celt(micSampleRate, 128, 2, true);\n// after\nvar celt = new Celt(48000, 128, Math.Min(2, inputChannels), true); // resample mic input to 48000 Hz","handlingStrategy":"fallback","validationCode":"public static bool IsCeltCompatible(int sampleRate, int bufferSize, int channels) =>\n    (sampleRate == 48000 || sampleRate == 24000) && bufferSize > 0 && channels is 1 or 2;","typeGuard":null,"tryCatchPattern":"try\n{\n    var celt = new Celt(sampleRate, bufferSize, channels, decoderOnly);\n}\ncatch (Exception ex) when (ex.Message.Contains(\"celt encoder/decoder\"))\n{\n    logger.Error(\"Native celt init failed; switching to uncompressed audio.\");\n    useCompressedAudio = false;\n}","preventionTips":["Deploy the native celt library with your application for every target platform.","Standardize on codec-supported sample rate/frame size/channel combinations.","Add a startup smoke test that constructs the codec and reports failures.","Match native library versions with Stride engine updates."],"tags":["audio","celt","native","codec","initialization"],"backgroundTag":"module-init-failed","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}