{"record":{"id":"d103c25214e6eeb6","repo":"ppy/osu","slug":"ruleset-is-not-available-locally","errorCode":null,"errorMessage":"Ruleset is not available locally.","messagePattern":"Ruleset is not available locally\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"osu.Game/Beatmaps/Formats/LegacyBeatmapDecoder.cs","lineNumber":278,"sourceCode":"                case @\"PreviewTime\":\r\n                    int time = Parsing.ParseInt(pair.Value);\r\n                    metadata.PreviewTime = time == -1 ? time : getOffsetTime(time);\r\n                    break;\r\n\r\n                case @\"SampleSet\":\r\n                    defaultSampleBank = Enum.Parse<LegacySampleBank>(pair.Value);\r\n                    break;\r\n\r\n                case @\"SampleVolume\":\r\n                    defaultSampleVolume = Parsing.ParseInt(pair.Value);\r\n                    break;\r\n\r\n                case @\"StackLeniency\":\r\n                    beatmap.StackLeniency = Parsing.ParseFloat(pair.Value);\r\n                    break;\r\n\r\n                case @\"Mode\":\r\n                    beatmap.BeatmapInfo.Ruleset = RulesetStore?.GetRuleset(Parsing.ParseInt(pair.Value)) ?? throw new ArgumentException(\"Ruleset is not available locally.\");\r\n                    break;\r\n\r\n                case @\"LetterboxInBreaks\":\r\n                    beatmap.LetterboxInBreaks = Parsing.ParseInt(pair.Value) == 1;\r\n                    break;\r\n\r\n                case @\"SpecialStyle\":\r\n                    beatmap.SpecialStyle = Parsing.ParseInt(pair.Value) == 1;\r\n                    break;\r\n\r\n                case @\"WidescreenStoryboard\":\r\n                    beatmap.WidescreenStoryboard = Parsing.ParseInt(pair.Value) == 1;\r\n                    break;\r\n\r\n                case @\"EpilepsyWarning\":\r\n                    beatmap.EpilepsyWarning = Parsing.ParseInt(pair.Value) == 1;\r\n                    break;\r\n\r","sourceCodeStart":260,"sourceCodeEnd":296,"githubUrl":"https://github.com/ppy/osu/blob/d9c73e12adff2feaae4a3e158d36fe5883faf6ca/osu.Game/Beatmaps/Formats/LegacyBeatmapDecoder.cs#L260-L296","documentation":"Thrown by LegacyBeatmapDecoder when the 'Mode:' field in the beatmap's [General] section specifies a ruleset ID that RulesetStore.GetRuleset cannot resolve (returns null). This means the ruleset DLL for that mode isn't available in the local installation. The exception includes the literal ruleset ID that was parsed.","triggerScenarios":"Decoding a .osu beatmap whose Mode field (0=osu, 1=taiko, 2=catch, 3=mania) points to a ruleset ID whose DLL is not loaded — e.g. Mode:4 for an experimental/custom ruleset that isn't installed, or a standard ruleset whose DLL failed to load. RulesetStore?.GetRuleset(id) returns null and the null-coalescing throw fires.","commonSituations":"Opening a beatmap designed for a custom ruleset (e.g. senton, rush) that isn't installed; a ruleset DLL that was uninstalled or failed to load at startup; a malformed Mode field that parses to an out-of-range integer (e.g. Mode:99).","solutions":["Install the ruleset DLL corresponding to the Mode value in the beatmap's [General] section.","If RulesetStore is null (Decoder.RegisterDependencies wasn't called), ensure the decoder has been properly initialized with a valid RulesetStore before decoding.","If the Mode field is corrupted, manually edit the .osu file to set a valid Mode value (0–3 for standard rulesets).","For custom rulesets, ensure the DLL is placed in the rulesets directory and loaded at application startup."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Check ruleset availability before decoding\nint modeId = Parsing.ParseInt(modeFieldValue);\nif (rulesetStore?.GetRuleset(modeId) == null)\n    throw new InvalidOperationException($\"Ruleset {modeId} is not available locally\");","typeGuard":null,"tryCatchPattern":"try\n{\n    var beatmap = decoder.Decode(stream);\n}\ncatch (ArgumentException ex) when (ex.Message.Contains(\"Ruleset is not available\"))\n{\n    Logger.Log($\"Required ruleset is not installed\", LoggingTarget.Database);\n}","preventionTips":["Ensure all required ruleset DLLs are installed before decoding beatmaps.","Call Decoder.RegisterDependencies(rulesetStore) with a non-null store before any decoding.","Handle the error gracefully by prompting the user to install the missing ruleset."],"tags":["beatmap-decoding","ruleset","ruleset-store","missing-dependency"],"backgroundTag":null,"analyzedSha":"d9c73e12adff2feaae4a3e158d36fe5883faf6ca","analyzedAt":"2026-08-13T14:12:54.015Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}