{"record":{"id":"c3c4c986aa62d123","repo":"github/copilot-sdk","slug":"generated-class-metaclassname-not-found-ens","errorCode":null,"errorMessage":"Generated class  + metaClassName +  not found. Ensure the CopilotToolProcessor annotation processor ran during compilation. Add the copilot-sdk-java dependency to your annotation processor path.","messagePattern":"Generated class  \\+ metaClassName \\+  not found\\. Ensure the CopilotToolProcessor annotation processor ran during compilation\\. Add the copilot-sdk-java dependency to your annotation processor path\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"java/sdk/src/main/java/com/github/copilot/rpc/ToolDefinition.java","lineNumber":933,"sourceCode":"        }\n    }\n\n    private static void requireNonNullHandler(Object handler, String toolName) {\n        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","sourceCodeStart":915,"sourceCodeEnd":951,"githubUrl":"https://github.com/github/copilot-sdk/blob/cd8cf15dc3f9e762615790aaed0a771a0f392755/java/sdk/src/main/java/com/github/copilot/rpc/ToolDefinition.java#L915-L951","documentation":"Tool registration via fromObject/fromClass depends on the CopilotToolProcessor annotation processor generating a 'ClassName$$CopilotToolMeta' metadata class at compile time. loadDefinitions loads this generated class reflectively; if it is absent (ClassNotFoundException), this IllegalStateException is thrown explaining that the annotation processor did not run and pointing at the annotation-processor path setup.","triggerScenarios":"Using ToolDefinition.fromObject(new X()) or fromClass(X.class) on a class annotated with @CopilotTool whose $$CopilotToolMeta class was never generated: processor not on the annotation processor path, compilation with -proc:none, incremental-build staleness, or running an old jar built before processing was configured.","commonSituations":"Maven/Gradle builds missing the copilot-sdk-java processor dependency in annotationProcessorPaths/annotationProcessor configuration; IDE builds (IntelliJ/Eclipse) with annotation processing disabled; clean-checkout CI builds missing the processor configuration that only existed on a developer machine; shading/repackaging that strips generated classes.","solutions":["Add copilot-sdk-java to your build's annotation processor path: in Maven, annotationProcessorPaths under maven-compiler-plugin; in Gradle, annotationProcessor 'com.github.copilot:copilot-sdk-java'.","Verify the generated class exists in target/classes (or build/classes) after compilation: look for YourClass$$CopilotToolMeta.class.","Run a clean rebuild (mvn clean compile / gradle clean build) to regenerate metadata after build-config changes.","Check the compiler isn't running with -proc:none and that IDE annotation processing is enabled."],"exampleFix":"// before (pom.xml)\n<plugin>\n  <artifactId>maven-compiler-plugin</artifactId>\n  <configuration><annotationProcessorPaths/></configuration>\n</plugin>\n\n// after (pom.xml)\n<annotationProcessorPaths>\n  <path>\n    <groupId>com.github.copilot</groupId>\n    <artifactId>copilot-sdk-java</artifactId>\n    <version>1.0.0</version>\n  </path>\n</annotationProcessorPaths>","handlingStrategy":"validation","validationCode":"String meta = Tools.class.getName() + \"$$CopilotToolMeta\";\ntry { Class.forName(meta, false, Tools.class.getClassLoader()); }\ncatch (ClassNotFoundException e) { throw new IllegalStateException(\"annotation processor did not run for \" + meta); }","typeGuard":null,"tryCatchPattern":"try { defs = ToolDefinition.fromObject(new Tools()); } catch (IllegalStateException e) {\n  log.error(\"metadata missing — check annotation processor config\", e);\n  throw e;\n}","preventionTips":["Configure the copilot-sdk-java processor in annotationProcessorPaths (Maven) or annotationProcessor (Gradle) from day one.","Enable annotation processing in the IDE build settings.","Add a smoke test that loads $$CopilotToolMeta classes after compilation.","Always run clean builds in CI so generated sources are regenerated."],"tags":["java","annotation-processing","build-configuration","classpath"],"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"}