github/copilot-sdk · error · IllegalArgumentException

instance must not be null

Error message

instance must not be null

What it means

Thrown by ToolDefinition.fromObject when the instance argument is null. fromObject discovers @CopilotTool-annotated methods on the instance's class and produces definitions; a null instance gives no class to inspect, so it is rejected immediately with this IllegalArgumentException.

Solutions

1. Ensure the tool instance is constructed/injected before calling fromObject
2. Null-check or use Objects.requireNonNull(instance) at the call site with a clear message
3. Fix DI configuration so the bean exists (check component scanning/qualifiers)
4. Catch IllegalArgumentException as a startup failure and fail fast with context about which tool set was being registered

Example fix

// before
MyTools tools = registry.get(MyTools.class); // may return null
List<ToolDefinition> defs = ToolDefinition.fromObject(tools);
// after
Objects.requireNonNull(tools, "MyTools bean not initialized");
List<ToolDefinition> defs = ToolDefinition.fromObject(tools);

Objects.requireNonNull(instance, "tool instance must be initialized before fromObject");

boolean canBuildDefinitions(Object o) { return o != null && ToolDefinition.fromClass(o.getClass()) != null; }

try { defs = ToolDefinition.fromObject(instance); } catch (IllegalArgumentException e) { throw new ToolRegistrationException("tool instance was null", e); }

When it happens

Trigger: Passing a null object reference to ToolDefinition.fromObject — e.g. a Spring/CDI bean that failed to inject, a lazy holder not yet initialized, or a map lookup returning null.

Common situations: Dependency injection containers returning null for unmanaged classes; conditional bean creation disabled by config; calling fromObject before initializing the tool host object.

Related errors

• clazz must not be null
• A Param descriptor is null for tool ' + toolName + '
• fromClass() requires all @CopilotTool methods to be static…
• Tool name must not be null or blank
• Tool description must not be null or blank

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

Appendix: source

Thrown at java/sdk/src/main/java/com/github/copilot/rpc/ToolDefinition.java:291

    /**
     * Discovers tool definitions from an object whose methods are annotated with
     * {@code @CopilotTool}. Requires that the {@code CopilotToolProcessor}
     * annotation processor ran at compile time (generating the
     * {@code $$CopilotToolMeta} companion class).
     *
     * @param instance
     *            the object containing {@code @CopilotTool}-annotated methods
     * @return list of tool definitions with working invocation handlers
     * @throws IllegalStateException
     *             if the generated {@code $$CopilotToolMeta} class is not found
     *             (annotation processor did not run)
     * @since 1.0.6
     */
    @CopilotExperimental
    public static List<ToolDefinition> fromObject(Object instance) {
        if (instance == null) {
            throw new IllegalArgumentException("instance must not be null");
        }
        Class<?> clazz = instance.getClass();
        return loadDefinitions(clazz, instance);
    }

    /**
     * Discovers tool definitions from a class with static
     * {@code @CopilotTool}-annotated methods. Requires that the
     * {@code CopilotToolProcessor} annotation processor ran at compile time
     * (generating the {@code $$CopilotToolMeta} companion class).
     *
     * @param clazz
     *            the class containing static {@code @CopilotTool}-annotated methods
     * @return list of tool definitions with working invocation handlers
     * @throws IllegalStateException
     *             if the generated {@code $$CopilotToolMeta} class is not found
     *             (annotation processor did not run)
     * @since 1.0.6

View on GitHub (pinned to cd8cf15dc3)