ppy/osu · error · ArgumentException

Provided client ID must be an integer.

Error message

Provided client ID must be an integer.

What it means

The --debug-client-id flag expects an integer value that is appended to the game's base name (e.g., osu!-2). If the value cannot be parsed as an int via int.TryParse, an ArgumentException is thrown. This occurs in the same switch-case as the debug-build check, so it only fires in debug builds.

Source

Thrown at osu.Desktop/Program.cs:98

            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)
                {
                    if (trySendIPCMessage(host, cwd, args))
                        return;

View on GitHub (pinned to d9c73e12ad)

Solutions

1. Provide a valid integer value after --debug-client-id.
2. If using key=value syntax, ensure the value side is numeric: --debug-client-id=2.
3. Validate the argument in your launch script before passing it to the process.

Example fix

// before
// args: ["--debug-client-id", "two"]

// after
// args: ["--debug-client-id", "2"]

// Validate the client ID before passing it to the process
string clientIdRaw = GetArgValue(args, "--debug-client-id");
if (!string.IsNullOrEmpty(clientIdRaw) && !int.TryParse(clientIdRaw, out _))
    throw new ArgumentException($"--debug-client-id must be an integer, got: {clientIdRaw}");

When it happens

Trigger: Passing --debug-client-id with a non-numeric value such as --debug-client-id abc, or providing the flag with no value at all (the arg-splitting logic yields an empty string when no = or trailing value is present).

Common situations: Typo in a launch script; argument value left blank; argument parser mis-splitting key=value pairs; copy-pasting a human-readable ID instead of a number.

Related errors

• Cannot use this argument in a non-debug build.
• Can't have zero or fewer stages.
• No valid beatmap files found in the beatmap archive.
• {setInfo.GetDisplayString()} already has a difficulty with t
• {Path} is not a valid archive

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