stride3d/stride · error · Exception

Failed to create an AudioLayer Source

Error message

Failed to create an AudioLayer Source

What it means

SoundInstance's constructor calls AudioLayer.SourceCreate to allocate a native audio source (OpenAL source) for a dynamic sound. If the native layer returns a zero pointer the instance cannot play audio, so the constructor throws. This means the underlying audio device/driver refused or failed to allocate another sound source.

Solutions

1. Check that the machine has a working audio output device and that AudioEngine was initialized with a valid device; re-create the AudioEngine if the device changed.
2. Reduce the number of simultaneously created SoundInstances (dispose instances you are done with) to stay under the device source limit.
3. Disable HRTF (useHrtf: false) or spatialization options that the backend may not support.
4. Wrap instance creation in try-catch and fall back to non-spatialized playback or silent mode on failure.

Example fix

// before
var instance = sound.CreateInstance(audioEngineListener, true, true, useHrtf: true);
// after
SoundInstance instance;
try
{
    instance = sound.CreateInstance(audioEngineListener, spatialized: true, useHrtf: false);
}
catch (Exception) // no audio device / source limit reached
{
    instance = null; // run without audio
}

// before creating instances
if (audioEngine.State == AudioEngineState.Invalidated)
    return; // audio subsystem is dead; skip audio path
if (!Audio.CanUseHrtfWithSpatialized)
    useHrtf = false;

bool HasValidAudioEngine(AudioEngine engine) => engine != null && engine.State != AudioEngineState.Invalidated;

SoundInstance instance = null;
try
{
    instance = sound.CreateInstance(listener, spatialized, useHrtf);
}
catch (Exception ex) when (ex.Message.Contains("AudioLayer Source"))
{
    logger.Warn(ex, "Native audio source unavailable; running muted.");
}

When it happens

Trigger: Creating a SoundInstance from a dynamic/ SoundBase when AudioLayer.SourceCreate returns IntPtr.Zero — e.g. after AudioEngine was initialized with an invalid/absent audio device, when the device's source limit is exhausted, or when requested parameters (spatialized + useHrtf, environment, directionalFactor) are unsupported by the backend.

Common situations: Machines with no audio output device or disabled audio service (headless servers, CI, VMs without sound), exhausting the platform's simultaneous-source limit by creating hundreds of instances, requesting HRTF spatialization on a backend that does not support it, or a stale AudioEngine after device hot-unplug.

Related errors

• Failed to create an AudioLayer Source
• Could not locate native executable
• Could not locate native library
• Failed to compile a sound asset, ffmpeg was not found.
• Failed to compile a sound asset, ffmpeg failed to convert

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

Appendix: source

Thrown at sources/engine/Stride.Audio/SoundInstance.cs:56

        /// <param name="mono">Set to true if the souce is mono, false if stereo</param>
        /// <param name="spatialized">If the SoundInstance will be used for spatialized audio set to true, if not false, if true mono must also be true</param>
        /// <param name="useHrtf">If the engine should use Hrtf for spatialization</param>
        /// <param name="directionalFactor"></param>
        /// <param name="environment"></param>
        public SoundInstance(AudioEngine engine, AudioListener listener, DynamicSoundSource dynamicSoundSource, int sampleRate, bool mono, bool spatialized = false, bool useHrtf = false, float directionalFactor = 0.0f, HrtfEnvironment environment = HrtfEnvironment.Small)
        {
            Listener = listener;
            this.engine = engine;
            this.spatialized = spatialized;
            soundSource = dynamicSoundSource;

            if (engine.State == AudioEngineState.Invalidated)
                return;

            Source = AudioLayer.SourceCreate(listener.Listener, sampleRate, dynamicSoundSource.MaxNumberOfBuffers, mono, spatialized, true, useHrtf, directionalFactor, environment);
            if (Source.Ptr == IntPtr.Zero)
            {
                throw new Exception("Failed to create an AudioLayer Source");
            }

            ResetStateToDefault();
        }

        internal SoundInstance() { }

        internal SoundInstance(Sound staticSound, AudioListener listener, bool forceLoadInMemory, bool useHrtf = false, float directionalFactor = 0.0f, HrtfEnvironment environment = HrtfEnvironment.Small)
        {
            Listener = listener;
            engine = staticSound.AudioEngine;
            sound = staticSound;
            spatialized = staticSound.Spatialized;

            var streamed = staticSound.StreamFromDisk && !forceLoadInMemory;

            if (engine.State == AudioEngineState.Invalidated)
                return;

View on GitHub (pinned to 96fad776d2)