CoplayDev/unity-mcp · error · InvalidOperationException

Unknown or unsupported command type: {commandName}

Error message

Unknown or unsupported command type: {commandName}

What it means

GetHandlerInfo looks up the requested command name in the _handlers dictionary, which is populated by reflection auto-discovery of [McpForUnityTool]/[McpForUnityResource] types during CommandRegistry.Initialize. A miss means no handler is registered under that name.

Source

Thrown at MCPForUnity/Editor/Tools/CommandRegistry.cs:255

                _handlers[commandName] = handlerInfo;
                return true;
            }
            catch (Exception ex)
            {
                McpLog.Error($"Failed to register {typeLabel} {type.Name}: {ex.Message}");
                return false;
            }
        }

        /// <summary>
        /// Get a command handler by name
        /// </summary>
        private static HandlerInfo GetHandlerInfo(string commandName)
        {
            if (!_handlers.TryGetValue(commandName, out var handler))
            {
                throw new InvalidOperationException(
                    $"Unknown or unsupported command type: {commandName}"
                );
            }
            return handler;
        }

        /// <summary>
        /// Get a synchronous command handler by name.
        /// Throws if the command is asynchronous.
        /// </summary>
        /// <param name="commandName"></param>
        /// <returns></returns>
        /// <exception cref="InvalidOperationException"></exception>
        public static Func<JObject, object> GetHandler(string commandName)
        {
            var handlerInfo = GetHandlerInfo(commandName);
            if (handlerInfo.IsAsync)
            {

View on GitHub (pinned to c21bf496bc)

Solutions

1. Enable the tool's group via manage_tools (non-core groups start disabled).
2. Verify the Python server and Unity plugin versions match.
3. Check the Unity console for 'Failed to register' errors from auto-discovery.
4. Ensure CommandRegistry.Initialize() has run before dispatching commands.

if (!CommandRegistry.IsRegistered(commandName))
{
    return new ErrorResponse($"Command '{commandName}' is not available. Enable its tool group or verify Python/Unity versions match.");
}

try
{
    var result = CommandRegistry.ExecuteCommand(commandName, @params, tcs);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Unknown or unsupported command type"))
{
    return new ErrorResponse($"'{commandName}' is not registered. Check that its tool group is enabled and versions match.");
}

When it happens

Trigger: The tool belongs to a non-core group (vfx, animation, ui, etc.) that starts disabled and was never toggled on; the Python server and Unity plugin versions are mismatched so names diverge; reflection discovery failed silently at startup; CommandRegistry.Initialize was never called.

Common situations: Calling an animation/vfx tool before enabling its group via manage_tools; updated the Python server but not the Unity package (or vice versa); a compile error in the package prevented a tool class from registering.

Related errors

• Failed to write config file '{path}': {ex.Message}
• The selected uvx executable does not exist
• The selected Claude CLI executable does not exist
• Invalid MCP base URL: {baseUrl}
• Repo URL is not a recognized GitHub repository URL: {repoUrl

AI-assisted analysis of CoplayDev/unity-mcp@c21bf496bc (2026-08-13). Data as JSON: /api/errors/c4e1b5bc9e677b8c. Report an issue: GitHub.