What causes "Failed to import new beatmap" in ppy/osu?

Check the import logs for the underlying reason ImportModel returned null — often a duplicate detection or realm error is logged just before the null return.

ppy/osu · error · InvalidOperationException

Failed to import new beatmap

Error message

Failed to import new beatmap

What it means

Thrown by BeatmapManager.Save/Import when beatmapImporter.ImportModel returns null, meaning the beatmap set failed to persist. ImportModel returning null typically signals that the model was rejected during the realm write — either a duplicate was found and merged silently but the merged result couldn't be returned, or the import transaction encountered an internal failure.

Source

Thrown at osu.Game/Beatmaps/BeatmapManager.cs:136

                }
            };

            var beatmapSet = new BeatmapSetInfo
            {
                DateAdded = DateTimeOffset.UtcNow,
                Beatmaps =
                {
                    new BeatmapInfo(ruleset, new BeatmapDifficulty(), metadata)
                }
            };

            foreach (BeatmapInfo b in beatmapSet.Beatmaps)
                b.BeatmapSet = beatmapSet;

            var imported = beatmapImporter.ImportModel(beatmapSet);

            if (imported == null)
                throw new InvalidOperationException("Failed to import new beatmap");

            return imported.PerformRead(s => GetWorkingBeatmap(s.Beatmaps.First()));
        }

        /// <summary>
        /// Add a new difficulty to the provided <paramref name="targetBeatmapSet"/> based on the provided <paramref name="referenceWorkingBeatmap"/>.
        /// The new difficulty will be backed by a <see cref="BeatmapInfo"/> model
        /// and represented by the returned <see cref="WorkingBeatmap"/>.
        /// </summary>
        /// <remarks>
        /// Contrary to <see cref="CopyExistingDifficulty"/>, this method does not preserve hitobjects and beatmap-level settings from <paramref name="referenceWorkingBeatmap"/>.
        /// The created beatmap will have zero hitobjects and will have default settings (including difficulty settings), but will preserve metadata and existing timing points.
        /// </remarks>
        /// <param name="targetBeatmapSet">The <see cref="BeatmapSetInfo"/> to add the new difficulty to.</param>
        /// <param name="referenceWorkingBeatmap">The <see cref="WorkingBeatmap"/> to use as a baseline reference when creating the new difficulty.</param>
        /// <param name="rulesetInfo">The ruleset with which the new difficulty should be created.</param>
        public virtual WorkingBeatmap CreateNewDifficulty(BeatmapSetInfo targetBeatmapSet, WorkingBeatmap referenceWorkingBeatmap, RulesetInfo rulesetInfo)
        {

View on GitHub (pinned to d9c73e12ad)

Solutions

Check the import logs for the underlying reason ImportModel returned null — often a duplicate detection or realm error is logged just before the null return.
Ensure the BeatmapSetInfo being imported has all required fields (Beatmaps list with valid BeatmapInfo, metadata, ruleset, hashes).
If importing a beatmap that may already exist, call GetExistingBeatmapSet or check for duplicates before importing.
Verify the Realm database isn't locked or in a migration-required state by checking realm access logs.

Defensive patterns

Strategy: try-catch

Try / catch

try
{
    var working = beatmapManager.Import(beatmapSet);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Failed to import new beatmap"))
{
    Logger.Log($"Import failed — check realm/database state and for duplicates", LoggingTarget.Database);
    // fall back to user-facing error or retry after dedup
}

Prevention

Populate all required fields on BeatmapSetInfo before importing (Beatmaps, metadata, ruleset, hashes).
Check for existing beatmap sets to avoid duplicate-import conflicts.
Monitor realm/database health and migration status before import operations.

When it happens

Trigger: Calling BeatmapManager.Import with a programmatically-constructed BeatmapSetInfo where ImportModel returns null — the model may violate a uniqueness constraint, or the underlying RealmArchiveModelImporter rejected it during the import transaction.

Common situations: Programmatically creating a BeatmapSetInfo and importing it without all required fields populated; importing a beatmap set that already exists and the dedup logic returns null instead of the existing entry; a Realm/database issue during the write transaction (locked realm, schema mismatch).

Related errors

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