stride3d/stride · error · AudioSystemInternalException

Tried to unregister soundEffectInstance while not contained…

Error message

Tried to unregister soundEffectInstance while not contained in the instance list.

What it means

SoundBase.UnregisterInstance throws AudioSystemInternalException when the given SoundInstance is not present in the sound's Instances list, i.e. disposal code is trying to unregister an instance that was never registered or already removed. This signals a broken internal bookkeeping invariant rather than a caller error.

Solutions

Ensure every instance is registered to its parent sound exactly once and disposed exactly once (guard with IsDisposed).
Don't share SoundInstance objects across different AudioEngine/AudioSystem instances.
If reproducible in normal use, report as a Stride bug with a reproduction; this exception indicates an engine invariant break.
Wrap teardown/Dispose logic so double-disposal cannot occur (idempotent dispose).

Example fix

// before
instance.Dispose();
instance.Dispose(); // second call triggers unregister failure
// after
if (!instance.IsDisposed)
{
    instance.Dispose();
}

Defensive patterns

Strategy: try-catch

Validate before calling

// Caller-side guard: dispose each instance at most once
bool disposedAlready = instance.IsDisposed;

Try / catch

try
{
    instance.Dispose();
}
catch (AudioSystemInternalException ex) when (ex.Message.Contains("unregister soundEffectInstance"))
{
    logger.Warn("Instance was not registered or already removed; possible double-dispose.");
}

Prevention

Make dispose paths idempotent and check IsDisposed before disposing.
Never dispose the same SoundInstance from two code paths (e.g. device reset + explicit cleanup).
Keep instances tied to a single AudioSystem; don't migrate them between engines.
If reproducible outside teardown races, file a Stride bug — this exception marks broken engine invariants.

When it happens

Trigger: Disposing a SoundInstance whose parent sound never registered it, double-disposing an instance, or audio-system teardown removing an instance twice (e.g. Dispose called from two paths).

Common situations: Race conditions between audio-device teardown and instance disposal; manually calling Dispose twice; mixing instances across AudioSystems so disposal hits the wrong registry.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

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

Appendix: source

Thrown at sources/engine/Stride.Audio/SoundBase.cs:125

        /// </summary>
        /// <param name="mainInstance">The main instance of the sound effect</param>
        internal void StopConcurrentInstances(SoundInstance mainInstance)
        {
            foreach (var instance in Instances)
            {
                if (instance != mainInstance)
                    instance.Stop();
            }
        }

        /// <summary>
        /// Unregister a disposed Instance.
        /// </summary>
        /// <param name="instance"></param>
        internal void UnregisterInstance(SoundInstance instance)
        {
            if (!Instances.Remove(instance))
                throw new AudioSystemInternalException("Tried to unregister soundEffectInstance while not contained in the instance list.");
        }

        /// <summary>
        /// Register a new instance to the soundEffect.
        /// </summary>
        /// <param name="instance">new instance to register.</param>
        protected void RegisterInstance(SoundInstance instance)
        {
            Instances.Add(instance);
            intancesCreationCount++;
        }

        /// <summary>
        /// The number of Instances Created so far by this SoundEffect. Used only to give a unique name to the SoundEffectInstance.
        /// </summary>
        protected int intancesCreationCount;

        /// <summary>

View on GitHub (pinned to 96fad776d2)