ppy/osu · error · RulesetLoadException

Ruleset could not be loaded (Type lookup failure)

Error message

Ruleset could not be loaded (Type lookup failure)

What it means

Thrown as RulesetLoadException by RulesetInfo.CreateInstance when Type.GetType(InstantiationInfo) returns null. The stored assembly-qualified type name could not be resolved to a loaded type, meaning the ruleset assembly is not loaded or the type was renamed/moved.

Source

Thrown at osu.Game/Rulesets/RulesetInfo.cs:105

        public RulesetInfo Clone() => new RulesetInfo
        {
            OnlineID = OnlineID,
            Name = Name,
            ShortName = ShortName,
            InstantiationInfo = InstantiationInfo,
            Available = Available,
            LastAppliedDifficultyVersion = LastAppliedDifficultyVersion,
        };

        public Ruleset CreateInstance()
        {
            if (!Available)
                throw new RulesetLoadException(@"Ruleset not available");

            var type = Type.GetType(InstantiationInfo);

            if (type == null)
                throw new RulesetLoadException(@"Type lookup failure");

            var ruleset = Activator.CreateInstance(type) as Ruleset;

            if (ruleset == null)
                throw new RulesetLoadException(@"Instantiation failure");

            // overwrite the pre-populated RulesetInfo with a potentially database attached copy.
            // TODO: figure if we still want/need this after switching to realm.
            // ruleset.RulesetInfo = this;

            return ruleset;
        }
    }
}

View on GitHub (pinned to d9c73e12ad)

Solutions

1. Install/restore the ruleset assembly referenced by InstantiationInfo.
2. If the type moved, re-scan rulesets so InstantiationInfo is updated to the current type name.
3. Guard on Available / catch RulesetLoadException and treat the ruleset as missing.

Example fix

// before
var instance = rulesetInfo.CreateInstance();

// after
if (!rulesetInfo.Available || Type.GetType(rulesetInfo.InstantiationInfo) == null)
    return null;
var instance = rulesetInfo.CreateInstance();

if (!rulesetInfo.Available || Type.GetType(rulesetInfo.InstantiationInfo) == null)
    return null;
var instance = rulesetInfo.CreateInstance();

bool TypeResolves(string instantiationInfo) => Type.GetType(instantiationInfo) != null;

try { var instance = rulesetInfo.CreateInstance(); }
catch (RulesetLoadException) { /* type not found: skip or re-scan */ }

When it happens

Trigger: InstantiationInfo (an assembly-qualified name persisted in the database) no longer resolves: the ruleset DLL is missing, the type's namespace/name changed, or the assembly failed to load.

Common situations: Ruleset DLL deleted or renamed; ruleset refactor moving the Ruleset class; version skew where stored InstantiationInfo points at an older/newer assembly identity than what is loaded.

Related errors

• Ruleset could not be loaded (Ruleset not available)
• Ruleset could not be loaded (Instantiation failure)
• Ruleset is not available locally.
• Only beatmaps in the osu, taiko, catch, or mania rulesets ca
• Creating ruleset instance failed when attempting to create p

AI-assisted analysis of ppy/osu@d9c73e12ad (2026-08-13). Data as JSON: /api/errors/8d20a293db317907. Report an issue: GitHub.