{"record":{"id":"7469f156f0ce0b58","repo":"stride3d/stride","slug":"failed-to-create-an-audiolayer-source","errorCode":null,"errorMessage":"Failed to create an AudioLayer Source","messagePattern":"Failed to create an AudioLayer Source","errorType":"exception","errorClass":"Exception","httpStatus":null,"severity":"error","filePath":"sources/engine/Stride.Audio/SoundInstance.cs","lineNumber":56,"sourceCode":"        /// <param name=\"mono\">Set to true if the souce is mono, false if stereo</param>\n        /// <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>\n        /// <param name=\"useHrtf\">If the engine should use Hrtf for spatialization</param>\n        /// <param name=\"directionalFactor\"></param>\n        /// <param name=\"environment\"></param>\n        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)\n        {\n            Listener = listener;\n            this.engine = engine;\n            this.spatialized = spatialized;\n            soundSource = dynamicSoundSource;\n\n            if (engine.State == AudioEngineState.Invalidated)\n                return;\n\n            Source = AudioLayer.SourceCreate(listener.Listener, sampleRate, dynamicSoundSource.MaxNumberOfBuffers, mono, spatialized, true, useHrtf, directionalFactor, environment);\n            if (Source.Ptr == IntPtr.Zero)\n            {\n                throw new Exception(\"Failed to create an AudioLayer Source\");\n            }\n\n            ResetStateToDefault();\n        }\n\n        internal SoundInstance() { }\n\n        internal SoundInstance(Sound staticSound, AudioListener listener, bool forceLoadInMemory, bool useHrtf = false, float directionalFactor = 0.0f, HrtfEnvironment environment = HrtfEnvironment.Small)\n        {\n            Listener = listener;\n            engine = staticSound.AudioEngine;\n            sound = staticSound;\n            spatialized = staticSound.Spatialized;\n\n            var streamed = staticSound.StreamFromDisk && !forceLoadInMemory;\n\n            if (engine.State == AudioEngineState.Invalidated)\n                return;","sourceCodeStart":38,"sourceCodeEnd":74,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/engine/Stride.Audio/SoundInstance.cs#L38-L74","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","Reduce the number of simultaneously created SoundInstances (dispose instances you are done with) to stay under the device source limit.","Disable HRTF (useHrtf: false) or spatialization options that the backend may not support.","Wrap instance creation in try-catch and fall back to non-spatialized playback or silent mode on failure."],"exampleFix":"// before\nvar instance = sound.CreateInstance(audioEngineListener, true, true, useHrtf: true);\n// after\nSoundInstance instance;\ntry\n{\n    instance = sound.CreateInstance(audioEngineListener, spatialized: true, useHrtf: false);\n}\ncatch (Exception) // no audio device / source limit reached\n{\n    instance = null; // run without audio\n}","handlingStrategy":"try-catch","validationCode":"// before creating instances\nif (audioEngine.State == AudioEngineState.Invalidated)\n    return; // audio subsystem is dead; skip audio path\nif (!Audio.CanUseHrtfWithSpatialized)\n    useHrtf = false;","typeGuard":"bool HasValidAudioEngine(AudioEngine engine) => engine != null && engine.State != AudioEngineState.Invalidated;","tryCatchPattern":"SoundInstance instance = null;\ntry\n{\n    instance = sound.CreateInstance(listener, spatialized, useHrtf);\n}\ncatch (Exception ex) when (ex.Message.Contains(\"AudioLayer Source\"))\n{\n    logger.Warn(ex, \"Native audio source unavailable; running muted.\");\n}","preventionTips":["Check AudioEngine.State before any instance creation.","Pool and dispose SoundInstances instead of allocating per play to stay under native source limits.","Avoid enabling HRTF/spatialization on platforms known not to support it.","Add an audio smoke test that creates and disposes one instance in CI-like environments."],"tags":["audio","native-interop","openal","device"],"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-16T04:17:20.429Z"}