{"record":{"id":"3c8dbf8d8619f1b1","repo":"github/copilot-sdk","slug":"failed-to-invoke-metaclassname-definitions","errorCode":null,"errorMessage":"Failed to invoke  + metaClassName + .definitions()","messagePattern":"Failed to invoke  \\+ metaClassName \\+ \\.definitions\\(\\)","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"java/sdk/src/main/java/com/github/copilot/rpc/ToolDefinition.java","lineNumber":937,"sourceCode":"        if (handler == null) {\n            throw new IllegalArgumentException(\"handler must not be null for tool '\" + toolName + \"'\");\n        }\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    private static List<ToolDefinition> loadDefinitions(Class<?> clazz, Object instance) {\n        String metaClassName = clazz.getName() + \"$$CopilotToolMeta\";\n        try {\n            Class<?> metaClass = Class.forName(metaClassName, true, clazz.getClassLoader());\n            var provider = (com.github.copilot.tool.CopilotToolMetadataProvider<Object>) metaClass\n                    .getDeclaredConstructor().newInstance();\n            return provider.definitions(instance, getConfiguredMapper());\n        } catch (ClassNotFoundException e) {\n            throw new IllegalStateException(\"Generated class \" + metaClassName + \" not found. \"\n                    + \"Ensure the CopilotToolProcessor annotation processor ran during compilation. \"\n                    + \"Add the copilot-sdk-java dependency to your annotation processor path.\", e);\n        } catch (ReflectiveOperationException e) {\n            throw new IllegalStateException(\"Failed to invoke \" + metaClassName + \".definitions()\", e);\n        }\n    }\n\n    /**\n     * Returns the SDK-configured ObjectMapper for tool argument/result\n     * serialization. Configuration mirrors\n     * {@code JsonRpcClient.createObjectMapper()}.\n     */\n    private static ObjectMapper getConfiguredMapper() {\n        return ConfiguredMapperHolder.INSTANCE;\n    }\n\n    /**\n     * Lazy holder for the configured ObjectMapper (thread-safe, initialized on\n     * first access).\n     */\n    private static final class ConfiguredMapperHolder {\n        static final ObjectMapper INSTANCE = createMapper();","sourceCodeStart":919,"sourceCodeEnd":955,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/rpc/ToolDefinition.java#L919-L955","documentation":"After locating the generated $$CopilotToolMeta class, loadDefinitions instantiates it and calls its definitions() method reflectively. Any ReflectiveOperationException during that step (constructor not accessible, instantiation failure, invocation error) is wrapped in this IllegalStateException. Unlike error 225, the metadata class exists but could not be constructed or invoked.","triggerScenarios":"The generated meta class exists but its no-arg constructor fails (e.g. its own initialization throws), the class was compiled against an incompatible SDK version so definitions() has an unexpected signature, or classloader/visibility issues prevent instantiation.","commonSituations":"Mixing SDK versions: tool classes compiled against an older copilot-sdk-java but running with a newer SDK (or vice versa) so the generated code's expected interface changed; hot-swap/incremental recompiles leaving stale generated classes; classloader isolation in app servers preventing instantiation.","solutions":["Run a clean rebuild so generated metadata and SDK version are in sync.","Align the copilot-sdk-java version used at compile time (processor) and runtime in all modules.","Check the cause (ex.getCause()) — if the meta-class constructor threw, fix the underlying initialization error in the tool class.","Verify the tool classes' jar actually contains the freshly generated meta classes and is not a stale artifact."],"exampleFix":"// before (build.gradle)\nimplementation 'com.github.copilot:copilot-sdk-java:1.0.0'\n// lib module still compiles against 0.9.0 → stale meta class\n\n// after (build.gradle)\n// same version everywhere\ndef copilotSdk = 'com.github.copilot:copilot-sdk-java:1.2.0'\nimplementation copilotSdk\nannotationProcessor copilotSdk","handlingStrategy":"try-catch","validationCode":"// ensure compile & runtime SDK versions match in the build script before registration","typeGuard":null,"tryCatchPattern":"try { defs = ToolDefinition.fromObject(new Tools()); }\ncatch (IllegalStateException e) {\n  log.error(\"failed to invoke generated metadata for {}\", e.getCause(), e);\n  throw e;\n}","preventionTips":["Keep one copilot-sdk-java version across all modules (use a version property/BOM).","Clean rebuild after SDK upgrades so generated metadata matches.","Read e.getCause() to find constructor/initialization failures early."],"tags":["java","reflection","annotation-processing","version-mismatch"],"backgroundTag":"class-not-found","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"}