{"record":{"id":"bfdbacc685dc1953","repo":"apache/skywalking","slug":"create-stream-getbuilder-getsimplename-metri","errorCode":null,"errorMessage":"Create {stream.getBuilder().getSimpleName()} metrics DAO failure.","messagePattern":"Create (.+?) metrics DAO failure\\.","errorType":"exception","errorClass":"UnexpectedException","httpStatus":null,"severity":"critical","filePath":"oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/worker/MetricsStreamProcessor.java","lineNumber":219,"sourceCode":"\n    private void create(ModuleDefineHolder moduleDefineHolder,\n                        StreamDefinition stream,\n                        Class<? extends Metrics> metricsClass,\n                        MetricStreamKind kind,\n                        StorageManipulationOpt opt) throws StorageException {\n        final StorageBuilderFactory storageBuilderFactory = moduleDefineHolder.find(StorageModule.NAME)\n                                                                              .provider()\n                                                                              .getService(StorageBuilderFactory.class);\n        final Class<? extends StorageBuilder> builder = storageBuilderFactory.builderOf(\n            metricsClass, stream.getBuilder());\n\n        StorageDAO storageDAO = moduleDefineHolder.find(StorageModule.NAME).provider().getService(StorageDAO.class);\n        IMetricsDAO metricsDAO;\n        try {\n            metricsDAO = storageDAO.newMetricsDao(builder.getDeclaredConstructor().newInstance());\n        } catch (InstantiationException | IllegalAccessException | NoSuchMethodException |\n                 InvocationTargetException e) {\n            throw new UnexpectedException(\"Create \" + stream.getBuilder().getSimpleName() + \" metrics DAO failure.\", e);\n        }\n\n        ModelRegistry modelSetter = moduleDefineHolder.find(CoreModule.NAME).provider().getService(ModelRegistry.class);\n        DownSamplingConfigService configService = moduleDefineHolder.find(CoreModule.NAME)\n                                                                    .provider()\n                                                                    .getService(DownSamplingConfigService.class);\n        TTLStatusQuery ttlStatusQuery = moduleDefineHolder.find(CoreModule.NAME)\n                                                          .provider()\n                                                          .getService(TTLStatusQuery.class);\n\n        MetricsPersistentWorker hourPersistentWorker = null;\n        MetricsPersistentWorker dayPersistentWorker = null;\n\n        MetricsTransWorker transWorker = null;\n\n        final MetricsExtension metricsExtension = metricsClass.getAnnotation(MetricsExtension.class);\n        /**\n         * All metrics default are `supportDownSampling` and `insertAndUpdate`, unless it has explicit definition.","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/worker/MetricsStreamProcessor.java#L201-L237","documentation":"MetricsStreamProcessor.create() reflectively builds the StorageBuilder for a metrics class and obtains an IMetricsDAO from the configured storage plugin. Wrapped reflection failures (missing/throwing/inaccessible no-arg builder constructor, abstract builder) are rethrown as this UnexpectedException, aborting OAP startup for that stream.","triggerScenarios":"A custom Metrics class's @Stream(builder=...) points to a builder without a public no-arg constructor, an abstract class, or a constructor that throws; or a storage plugin jar version mismatch makes instantiation fail.","commonSituations":"Adding a custom OAL metrics function/plugin and misdeclaring its builder; deploying OAP with mixed-version storage plugin jars in oap-libs; a shaded/fat jar breaking reflective access under a restrictive module path.","solutions":["Read the cause exception: NoSuchMethodException -> add public no-arg constructor; InstantiationException -> make builder concrete; InvocationTargetException -> fix the exception thrown inside the builder constructor","Verify the @Stream annotation's builder class is public, top-level-accessible, and compiled against the current server-core","Clean and rebuild: 'mvnw clean install' to remove stale jars, and confirm no duplicate plugin versions in the distribution's oap-libs"],"exampleFix":"// before\n@Stream(name = \"my_metric\", builder = MyMetric.Builder.class, ...)\npublic static class Builder { /* only a private constructor */ }\n// after\npublic static class Builder implements StorageBuilder {\n    public Builder() {}\n    // storageBuilder0 / entity2Storage implementations\n}","handlingStrategy":"try-catch","validationCode":"// plugin self-check at test time\nassertNotNull(MyMetric.Builder.class.getDeclaredConstructor()); // must exist and be public\nassertTrue(StorageBuilder.class.isAssignableFrom(MyMetric.Builder.class));","typeGuard":null,"tryCatchPattern":"At startup this must fail fast (do not catch); in integration tests, catch UnexpectedException, unwrap with getCause(), and assert it identifies the exact builder defect (NoSuchMethodException vs InvocationTargetException).","preventionTips":["Standardize builder classes: public static, implements StorageBuilder, explicit public no-arg constructor","Run the OAP boot once in CI for custom plugins — DAO creation errors surface immediately","Avoid custom builder constructors with required arguments"],"tags":["stream-processor","storage","reflection","startup","metrics","plugin"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}