stride3d/stride · error · Exception

Failed to create an instance of the celt encoder/decoder.

Error message

Failed to create an instance of the celt encoder/decoder.

What it means

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.

Solutions

1. Use codec-supported parameters (e.g. 48000 Hz sample rate, standard frame size, 1-2 channels).
2. Verify the native celt binary ships with and matches your build/platform.
3. Catch the failure at startup and fall back to uncompressed audio or disable audio features.
4. Update Stride/native dependencies to a matched version set.

Example fix

// before
var celt = new Celt(micSampleRate, 128, 2, true);
// after
var celt = new Celt(48000, 128, Math.Min(2, inputChannels), true); // resample mic input to 48000 Hz

public static bool IsCeltCompatible(int sampleRate, int bufferSize, int channels) =>
    (sampleRate == 48000 || sampleRate == 24000) && bufferSize > 0 && channels is 1 or 2;

try
{
    var celt = new Celt(sampleRate, bufferSize, channels, decoderOnly);
}
catch (Exception ex) when (ex.Message.Contains("celt encoder/decoder"))
{
    logger.Error("Native celt init failed; switching to uncompressed audio.");
    useCompressedAudio = false;
}

When it happens

Trigger: Constructing Celt with sampleRate/bufferSize/channels the native xnCeltCreate cannot honor, or when the native celt library is missing, mismatched, or fails to allocate.

Common situations: 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.

Related errors

• Failed to create Celt custom mode.
• Failed to create Celt decoder.
• Failed to create Celt encoder.
• Failed to initialize the audio native layer.
• Celt decoder returned a wrong decoding buffer size.

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/2934bd8495e1e72c. Report an issue: GitHub.

Appendix: source

Thrown at sources/engine/Stride.Audio/Native/Celt.cs:45

            NativeInvoke.PreLoad();
        }

        /// <summary>
        /// Initialize the Celt encoder/decoder
        /// </summary>
        /// <param name="sampleRate">Required sample rate</param>
        /// <param name="bufferSize">Required buffer size</param>
        /// <param name="channels">Required channels</param>
        /// <param name="decoderOnly">If we desire only to decode set this to true</param>
        public Celt(int sampleRate, int bufferSize, int channels, bool decoderOnly)
        {
            SampleRate = sampleRate;
            BufferSize = bufferSize;
            Channels = channels;
            celtPtr = xnCeltCreate(sampleRate, bufferSize, channels, decoderOnly);
            if (celtPtr == IntPtr.Zero)
            {
                throw new Exception("Failed to create an instance of the celt encoder/decoder.");
            }
        }

        /// <summary>
        /// Dispose the Celt encoder/decoder
        /// Do not call Encode or Decode after disposal!
        /// </summary>
        public void Dispose()
        {
            if (celtPtr != IntPtr.Zero)
            {
                xnCeltDestroy(celtPtr);
                celtPtr = IntPtr.Zero;
            }
        }

        /// <summary>
        /// Decodes compressed celt data into PCM 16 bit shorts

View on GitHub (pinned to 96fad776d2)