ppy/osu · error · ArgumentException

Ruleset is not available locally.

Error message

Ruleset is not available locally.

What it means

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.

Source

Thrown at osu.Game/Beatmaps/Formats/LegacyBeatmapDecoder.cs:278

                case @"PreviewTime":
                    int time = Parsing.ParseInt(pair.Value);
                    metadata.PreviewTime = time == -1 ? time : getOffsetTime(time);
                    break;

                case @"SampleSet":
                    defaultSampleBank = Enum.Parse<LegacySampleBank>(pair.Value);
                    break;

                case @"SampleVolume":
                    defaultSampleVolume = Parsing.ParseInt(pair.Value);
                    break;

                case @"StackLeniency":
                    beatmap.StackLeniency = Parsing.ParseFloat(pair.Value);
                    break;

                case @"Mode":
                    beatmap.BeatmapInfo.Ruleset = RulesetStore?.GetRuleset(Parsing.ParseInt(pair.Value)) ?? throw new ArgumentException("Ruleset is not available locally.");
                    break;

                case @"LetterboxInBreaks":
                    beatmap.LetterboxInBreaks = Parsing.ParseInt(pair.Value) == 1;
                    break;

                case @"SpecialStyle":
                    beatmap.SpecialStyle = Parsing.ParseInt(pair.Value) == 1;
                    break;

                case @"WidescreenStoryboard":
                    beatmap.WidescreenStoryboard = Parsing.ParseInt(pair.Value) == 1;
                    break;

                case @"EpilepsyWarning":
                    beatmap.EpilepsyWarning = Parsing.ParseInt(pair.Value) == 1;
                    break;

View on GitHub (pinned to d9c73e12ad)

Solutions

1. Install the ruleset DLL corresponding to the Mode value in the beatmap's [General] section.
2. If RulesetStore is null (Decoder.RegisterDependencies wasn't called), ensure the decoder has been properly initialized with a valid RulesetStore before decoding.
3. If the Mode field is corrupted, manually edit the .osu file to set a valid Mode value (0–3 for standard rulesets).
4. For custom rulesets, ensure the DLL is placed in the rulesets directory and loaded at application startup.

// Check ruleset availability before decoding
int modeId = Parsing.ParseInt(modeFieldValue);
if (rulesetStore?.GetRuleset(modeId) == null)
    throw new InvalidOperationException($"Ruleset {modeId} is not available locally");

try
{
    var beatmap = decoder.Decode(stream);
}
catch (ArgumentException ex) when (ex.Message.Contains("Ruleset is not available"))
{
    Logger.Log($"Required ruleset is not installed", LoggingTarget.Database);
}

When it happens

Trigger: 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.

Common situations: 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).

Related errors

• Beat length cannot be NaN in a timing control point
• Only beatmaps in the osu, taiko, catch, or mania rulesets ca
• Color specified in incorrect format (should be R,G,B or R,G,
• Color must be specified with 8-bit integer components
• Value is too low

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