ppy/osu · error · InvalidOperationException

Cannot use this argument in a non-debug build.

Error message

Cannot use this argument in a non-debug build.

What it means

The osu! desktop launcher exposes a --debug-client-id CLI flag used to assign a unique game-name suffix when running multiple client instances for debugging. This flag is gated behind DebugUtils.IsDebugBuild, which is only true in Debug-compiled builds. Passing the flag in a Release or non-debug build is rejected because the multi-instance debug feature is compiled out.

Source

Thrown at osu.Desktop/Program.cs:95

            string gameName = base_game_name;
            bool tournamentClient = false;

            foreach (string arg in args)
            {
                string[] split = arg.Split('=');

                string key = split[0];
                string val = split.Length > 1 ? split[1] : string.Empty;

                switch (key)
                {
                    case "--tournament":
                        tournamentClient = true;
                        break;

                    case "--debug-client-id":
                        if (!DebugUtils.IsDebugBuild)
                            throw new InvalidOperationException("Cannot use this argument in a non-debug build.");

                        if (!int.TryParse(val, out int clientID))
                            throw new ArgumentException("Provided client ID must be an integer.");

                        gameName = $"{base_game_name}-{clientID}";
                        break;
                }
            }

            var hostOptions = new HostOptions
            {
                IPCPipeName = !tournamentClient ? OsuGame.IPC_PIPE_NAME : null,
                FriendlyGameName = OsuGameBase.GAME_NAME,
            };

            using (DesktopGameHost host = Host.GetSuitableDesktopHost(gameName, hostOptions))
            {
                if (!host.IsPrimaryInstance)

View on GitHub (pinned to d9c73e12ad)

Solutions

1. Remove the --debug-client-id flag from your launch arguments when running a release build.
2. Rebuild osu.Desktop in Debug configuration (e.g., dotnet build -c Debug) if you need multi-instance debug support.
3. Conditionally include the flag only in a debug-specific launch profile or script that checks the build configuration.

Example fix

// before
// launch args: osu!.exe --debug-client-id 2  (on a release build)

// after
// launch args: osu!.exe
// or rebuild in Debug: dotnet build -c Debug osu.Desktop

// Before passing --debug-client-id, verify the build supports it
#if DEBUG
    args = args.Append("--debug-client-id").Append(clientId.ToString()).ToArray();
#endif
// Or check at runtime before launching:
bool isDebugBuild = System.Diagnostics.Debugger.IsAttached || DebugUtils.IsDebugBuild;
if (!isDebugBuild && args.Contains("--debug-client-id"))
    throw new InvalidOperationException("--debug-client-id requires a debug build.");

When it happens

Trigger: Passing --debug-client-id <value> on the command line when the osu.Desktop binary was compiled with DebugUtils.IsDebugBuild == false (Release/ReleaseDebug configuration). The switch-case for --debug-client-id checks the conditional and throws InvalidOperationException immediately.

Common situations: Running a published or release build of osu! while a launch script, shortcut, or IDE profile still includes the --debug-client-id flag. Upgrading from a debug build to a release build without cleaning up launch arguments.

Related errors

• Provided client ID must be an integer.
• Beatmap submission not supported in this configuration!
• Beatmap submission not supported in this configuration!
• Beatmap submission not supported in this configuration!

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