ppy/osu · error · ArgumentException

No valid beatmap files found in the beatmap archive.

Error message

No valid beatmap files found in the beatmap archive.

What it means

Thrown by BeatmapImporter when, after iterating every file inside an imported beatmap archive, zero valid beatmap (.osu) files were decoded and added to the result list. The archive either contained no .osu files at all, or every .osu file failed to decode and was skipped silently during the loop.

Source

Thrown at osu.Game/Beatmaps/BeatmapImporter.cs:454

                    };

                    var beatmap = new BeatmapInfo(ruleset, difficulty, metadata)
                    {
                        Hash = hash,
                        DifficultyName = decodedInfo.DifficultyName,
                        OnlineID = decodedInfo.OnlineID,
                        BeatDivisor = decodedInfo.BeatDivisor,
                        MD5Hash = memoryStream.ComputeMD5Hash(),
                        EndTimeObjectCount = decoded.HitObjects.Count(h => h is IHasDuration),
                        TotalObjectCount = decoded.HitObjects.Count
                    };

                    beatmaps.Add(beatmap);
                }
            }

            if (!beatmaps.Any())
                throw new ArgumentException("No valid beatmap files found in the beatmap archive.");

            return beatmaps;
        }
    }
}

View on GitHub (pinned to d9c73e12ad)

Solutions

1. Verify the archive actually contains .osu files before importing — open the zip and confirm the presence of beatmap files.
2. Ensure the .osu files start with the correct format magic (e.g. 'osu file format vN') so the decoder can identify them.
3. If the archive is a skin or other non-beatmap content, route it through the correct importer instead of BeatmapImporter.
4. If files exist but fail to decode, check Decoder.GetDecoder logs for which files were skipped and fix the root cause (truncation, encoding, format corruption).

Example fix

// before
var importTask = new ImportTask(path);
beatmapImporter.Import(importTask); // throws if no .osu files

// after
using var reader = importTask.GetReader();
bool hasBeatmapFiles = reader.Filenames.Any(f => f.EndsWith(".osu", StringComparison.OrdinalIgnoreCase));
if (!hasBeatmapFiles)
    throw new InvalidOperationException($"{path} contains no .osu beatmap files");
beatmapImporter.Import(new ImportTask(path));

// Check archive contents before importing
using var reader = importTask.GetReader();
bool hasBeatmapFiles = reader.Filenames
    .Any(f => f.EndsWith(".osu", StringComparison.OrdinalIgnoreCase));
if (!hasBeatmapFiles)
    throw new InvalidOperationException("Archive contains no .osu files");

try
{
    beatmapImporter.Import(task);
}
catch (ArgumentException ex) when (ex.Message.Contains("No valid beatmap files"))
{
    Logger.Log($"Import failed: archive has no valid beatmaps", LoggingTarget.Database);
}

When it happens

Trigger: Calling beatmap import with an archive (zip, directory, or single file) that contains no decodable .osu beatmap files — e.g. a zip with only audio/images, a skin archive mistaken for a beatmap, or .osu files whose first-line magic doesn't match any registered decoder so they produce no BeatmapInfo.

Common situations: User drags a skin zip onto the beatmap import window; a corrupt or partially downloaded archive where the .osu files are truncated; a packaged mapset where .osu files were deleted or renamed with an unrecognized extension before zipping.

Related errors

• {Path} is not a valid archive
• Provided client ID must be an integer.
• Can't have zero or fewer stages.
• Failed to import new beatmap
• {setInfo.GetDisplayString()} already has a difficulty with t

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