{"record":{"id":"77d2b5fc398a346f","repo":"ppy/osu","slug":"creating-ruleset-instance-failed-when-attempting-t","errorCode":null,"errorMessage":"Creating ruleset instance failed when attempting to create playable beatmap.","messagePattern":"Creating ruleset instance failed when attempting to create playable beatmap\\.","errorType":"exception","errorClass":"RulesetLoadException","httpStatus":null,"severity":"error","filePath":"osu.Game/Beatmaps/WorkingBeatmap.cs","lineNumber":282,"sourceCode":"            {\r\n                using (var cancellationTokenSource = new CancellationTokenSource(10_000))\r\n                {\r\n                    // don't apply the default timeout when debugger is attached (may be breakpointing / debugging).\r\n                    return GetPlayableBeatmap(ruleset, mods ?? Array.Empty<Mod>(), Debugger.IsAttached ? CancellationToken.None : cancellationTokenSource.Token);\r\n                }\r\n            }\r\n            catch (OperationCanceledException)\r\n            {\r\n                throw new BeatmapLoadTimeoutException(BeatmapInfo);\r\n            }\r\n        }\r\n\r\n        public virtual IBeatmap GetPlayableBeatmap(IRulesetInfo ruleset, IReadOnlyList<Mod> mods, CancellationToken token)\r\n        {\r\n            var rulesetInstance = ruleset.CreateInstance();\r\n\r\n            if (rulesetInstance == null)\r\n                throw new RulesetLoadException(\"Creating ruleset instance failed when attempting to create playable beatmap.\");\r\n\r\n            IBeatmapConverter converter = CreateBeatmapConverter(Beatmap, rulesetInstance);\r\n\r\n            // Check if the beatmap can be converted\r\n            if (Beatmap.HitObjects.Count > 0 && !converter.CanConvert())\r\n                throw new BeatmapInvalidForRulesetException($\"{nameof(Beatmaps.Beatmap)} can not be converted for the ruleset (ruleset: {ruleset.InstantiationInfo}, converter: {converter}).\");\r\n\r\n            // Apply conversion mods\r\n            foreach (var mod in mods.OfType<IApplicableToBeatmapConverter>())\r\n            {\r\n                token.ThrowIfCancellationRequested();\r\n                mod.ApplyToBeatmapConverter(converter);\r\n            }\r\n\r\n            // Convert\r\n            IBeatmap converted = converter.Convert(token);\r\n\r\n            // Apply conversion mods to the result\r","sourceCodeStart":264,"sourceCodeEnd":300,"githubUrl":"https://github.com/ppy/osu/blob/d9c73e12adff2feaae4a3e158d36fe5883faf6ca/osu.Game/Beatmaps/WorkingBeatmap.cs#L264-L300","documentation":"Thrown by WorkingBeatmap.GetPlayableBeatmap when ruleset.CreateInstance() returns null. A null return means the IRulesetInfo.InstantiationInfo could not be resolved to a live Ruleset object — typically the ruleset DLL isn't loaded/available in the current AppDomain. This is a RulesetLoadException.","triggerScenarios":"Calling GetPlayableBeatmap with a RulesetInfo whose InstantiationInfo references a ruleset assembly that is not present (uninstalled ruleset, removed DLL, version mismatch). Also when the ruleset was deserialised from realm with a stale type name.","commonSituations":"A score or beatmap references a custom/legacy ruleset the user uninstalled; running on a clean install that lacks the ruleset add-on; realm data migrated from another machine whose rulesets weren't copied.","solutions":["Ensure the ruleset assembly is installed and loadable; check the InstantiationInfo string resolves (assembly name + type name present and version-compatible).","Guard upstream: verify ruleset.CreateInstance() is non-null before calling GetPlayableBeatmap, and skip/handle unloaded rulesets.","If the ruleset is genuinely unavailable, present the user with a 'ruleset missing' message rather than letting gameplay/simulation crash."],"exampleFix":"// before\nIBeatmap playable = working.GetPlayableBeatmap(rulesetInfo, mods);\n\n// after\nvar rulesetInstance = rulesetInfo.CreateInstance();\nif (rulesetInstance == null)\n    throw new RulesetLoadException($\"Ruleset '{rulesetInfo.InstantiationInfo}' is not available.\");\nIBeatmap playable = working.GetPlayableBeatmap(rulesetInfo, mods);","handlingStrategy":"validation","validationCode":"var instance = rulesetInfo.CreateInstance();\nif (instance == null)\n    throw new RulesetLoadException($\"Ruleset '{rulesetInfo.InstantiationInfo}' is not available.\");\nvar playable = working.GetPlayableBeatmap(rulesetInfo, mods);","typeGuard":"static bool IsRulesetAvailable(IRulesetInfo ruleset)\n    => ruleset?.CreateInstance() != null;","tryCatchPattern":"try { var playable = working.GetPlayableBeatmap(ruleset, mods); }\ncatch (RulesetLoadException) { /* prompt user to install/enable the ruleset */ }","preventionTips":["Check ruleset.CreateInstance() != null before any gameplay/simulation call.","Keep ruleset InstantiationInfo in realm consistent with installed assembly versions.","Handle missing rulesets gracefully in UI (disable, show 'install ruleset')."],"tags":["ruleset","plugin-loading","beatmap","gameplay"],"backgroundTag":null,"analyzedSha":"d9c73e12adff2feaae4a3e158d36fe5883faf6ca","analyzedAt":"2026-08-13T14:12:54.015Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}