github/copilot-sdk · error · IllegalArgumentException

Invalid mcp tool name: must not be null or empty.

Error message

Invalid mcp tool name: must not be null or empty. (template: Invalid <kind> tool name: must not be null or empty.)

What it means

ToolSet.validateName enforces that every tool name added via addBuiltIn/addCustom/addMcp is non-null and non-empty. When a null or empty name is passed (here for kind "mcp"), an IllegalArgumentException with this templated message is thrown before any entry is added to the set.

Solutions

1. Pass a non-empty tool name string to addMcp (and addBuiltIn/addCustom).
2. Validate/filter names before building the ToolSet, skipping entries with blank names.
3. Fix the configuration/env source supplying the MCP server name so it is populated.

Example fix

// before
String name = config.get("mcp.tool"); // null
set.addMcp(name);

// after
String name = config.get("mcp.tool");
if (name != null && !name.isEmpty()) set.addMcp(name);

if (name == null || name.isEmpty()) throw new IllegalArgumentException("mcp tool name required");
set.addMcp(name);

static boolean validToolName(String n) { return n != null && !n.isEmpty(); }

try { set.addMcp(name); } catch (IllegalArgumentException e) {
  log.error("skipping invalid tool name: {}", e.getMessage());
}

When it happens

Trigger: Calling toolSet.addMcp(null) or addMcp("") — usually a variable holding the server/tool name that is null or empty, or a missing config value for the MCP server name.

Common situations: MCP server names read from config/env that is unset; string splitting producing empty tokens; optional tool names defaulted to null instead of being skipped.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• Invalid mcp tool name
• Invalid tool name ' ': tool names must match…
• CliUrl is mutually exclusive with CliPath
• TcpConnectionToken must be a non-empty string
• Invalid value ' '. Expected 'inprocess', 'stdio', or unset.

AI-assisted analysis of github/copilot-sdk@cd8cf15dc3 (2026-09-09). Data as JSON: /api/errors/650ca66f0d1092ad. Report an issue: GitHub.

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/rpc/ToolSet.java:112

     * server.
     *
     * @param toolName
     *            the runtime's canonical wire name for the MCP tool (e.g.
     *            {@code "github-list_issues"}), or {@code "*"} to match all MCP
     *            tools from any server
     * @return this {@code ToolSet} for chaining
     * @throws IllegalArgumentException
     *             if toolName is null, empty, or contains invalid characters
     */
    public ToolSet addMcp(String toolName) {
        validateName("mcp", toolName);
        add("mcp:" + toolName);
        return this;
    }

    private static void validateName(String kind, String name) {
        if (name == null || name.isEmpty()) {
            throw new IllegalArgumentException("Invalid " + kind + " tool name: must not be null or empty.");
        }
        if ("*".equals(name)) {
            return;
        }
        if (!VALID_TOOL_NAME.matcher(name).matches()) {
            throw new IllegalArgumentException("Invalid " + kind + " tool name '" + name
                    + "': tool names must match /^[a-zA-Z0-9_-]+$/ or be the wildcard '*'.");
        }
    }
}

View on GitHub (pinned to cd8cf15dc3)