{"record":{"id":"f4a0490d656a2f44","repo":"github/copilot-sdk","slug":"instance-must-not-be-null","errorCode":null,"errorMessage":"instance must not be null","messagePattern":"instance must not be null","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"java/sdk/src/main/java/com/github/copilot/rpc/ToolDefinition.java","lineNumber":291,"sourceCode":"\n    /**\n     * Discovers tool definitions from an object whose methods are annotated with\n     * {@code @CopilotTool}. Requires that the {@code CopilotToolProcessor}\n     * annotation processor ran at compile time (generating the\n     * {@code $$CopilotToolMeta} companion class).\n     *\n     * @param instance\n     *            the object containing {@code @CopilotTool}-annotated methods\n     * @return list of tool definitions with working invocation handlers\n     * @throws IllegalStateException\n     *             if the generated {@code $$CopilotToolMeta} class is not found\n     *             (annotation processor did not run)\n     * @since 1.0.6\n     */\n    @CopilotExperimental\n    public static List<ToolDefinition> fromObject(Object instance) {\n        if (instance == null) {\n            throw new IllegalArgumentException(\"instance must not be null\");\n        }\n        Class<?> clazz = instance.getClass();\n        return loadDefinitions(clazz, instance);\n    }\n\n    /**\n     * Discovers tool definitions from a class with static\n     * {@code @CopilotTool}-annotated methods. Requires that the\n     * {@code CopilotToolProcessor} annotation processor ran at compile time\n     * (generating the {@code $$CopilotToolMeta} companion class).\n     *\n     * @param clazz\n     *            the class containing static {@code @CopilotTool}-annotated methods\n     * @return list of tool definitions with working invocation handlers\n     * @throws IllegalStateException\n     *             if the generated {@code $$CopilotToolMeta} class is not found\n     *             (annotation processor did not run)\n     * @since 1.0.6","sourceCodeStart":273,"sourceCodeEnd":309,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/rpc/ToolDefinition.java#L273-L309","documentation":"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.","triggerScenarios":"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.","commonSituations":"Dependency injection containers returning null for unmanaged classes; conditional bean creation disabled by config; calling fromObject before initializing the tool host object.","solutions":["Ensure the tool instance is constructed/injected before calling fromObject","Null-check or use Objects.requireNonNull(instance) at the call site with a clear message","Fix DI configuration so the bean exists (check component scanning/qualifiers)","Catch IllegalArgumentException as a startup failure and fail fast with context about which tool set was being registered"],"exampleFix":"// before\nMyTools tools = registry.get(MyTools.class); // may return null\nList<ToolDefinition> defs = ToolDefinition.fromObject(tools);\n// after\nObjects.requireNonNull(tools, \"MyTools bean not initialized\");\nList<ToolDefinition> defs = ToolDefinition.fromObject(tools);","handlingStrategy":"validation","validationCode":"Objects.requireNonNull(instance, \"tool instance must be initialized before fromObject\");","typeGuard":"boolean canBuildDefinitions(Object o) { return o != null && ToolDefinition.fromClass(o.getClass()) != null; }","tryCatchPattern":"try { defs = ToolDefinition.fromObject(instance); } catch (IllegalArgumentException e) { throw new ToolRegistrationException(\"tool instance was null\", e); }","preventionTips":["Verify DI/container wiring so tool beans are never null at registration","Initialize tool hosts before scanning them","Fail fast at startup with requireNonNull for all tool instances"],"tags":["java","null-argument","tool-registration"],"backgroundTag":"null-argument","analyzedSha":"cd8cf15dc3f9e762615790aaed0a771a0f392755","analyzedAt":"2026-09-09T18:32:31.973Z","contentChangedAt":"2026-09-09T18:32:31.973Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}