{"record":{"id":"627db744c69cbaf7","repo":"apache/skywalking","slug":"create-stream-builder-getsimplename-top-n-re","errorCode":null,"errorMessage":"Create {stream.builder().getSimpleName()} top n record DAO failure.","messagePattern":"Create (.+?) top n record 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/TopNStreamProcessor.java","lineNumber":89,"sourceCode":"        }\n        this.topNWorkerReportCycle = topNWorkerReportCycle;\n    }\n\n    public void create(ModuleDefineHolder moduleDefineHolder,\n                       Stream stream,\n                       Class<? extends TopN> topNClass) throws StorageException {\n        final StorageBuilderFactory storageBuilderFactory = moduleDefineHolder.find(StorageModule.NAME)\n                                                                              .provider()\n                                                                              .getService(StorageBuilderFactory.class);\n        final Class<? extends StorageBuilder> builder = storageBuilderFactory.builderOf(topNClass, stream.builder());\n\n        StorageDAO storageDAO = moduleDefineHolder.find(StorageModule.NAME).provider().getService(StorageDAO.class);\n        IRecordDAO recordDAO;\n        try {\n            recordDAO = storageDAO.newRecordDao(builder.getDeclaredConstructor().newInstance());\n        } catch (InstantiationException | IllegalAccessException | NoSuchMethodException |\n                 InvocationTargetException e) {\n            throw new UnexpectedException(\n                \"Create \" + stream.builder().getSimpleName() + \" top n record DAO failure.\", e);\n        }\n\n        ModelRegistry modelSetter = moduleDefineHolder.find(CoreModule.NAME).provider().getService(ModelRegistry.class);\n        // Top N metrics doesn't read data from database during the persistent process. Keep the timeRelativeID == false always.\n        Model model = modelSetter.add(\n            topNClass, stream.scopeId(),\n            new Storage(stream.name(), false, DownSampling.Second),\n            StorageManipulationOpt.schemaCreateIfAbsent());\n\n        TopNWorker persistentWorker = new TopNWorker(\n            moduleDefineHolder, model, topSize, topNWorkerReportCycle * 60 * 1000L, recordDAO, topNClass);\n        persistentWorkers.add(persistentWorker);\n        workers.put(topNClass, persistentWorker);\n    }\n\n    @Override\n    public void in(TopN topN) {","sourceCodeStart":71,"sourceCodeEnd":107,"githubUrl":"https://github.com/apache/skywalking/blob/102af09b4a56064e22050dded10e2c52e490d040/oap-server/server-core/src/main/java/org/apache/skywalking/oap/server/core/analysis/worker/TopNStreamProcessor.java#L71-L107","documentation":"TopNStreamProcessor.create() reflectively instantiates the StorageBuilder of a @Stream TopN class and requests an IRecordDAO for it. Reflection failures — missing public no-arg constructor, abstract builder, constructor that throws — are wrapped as this UnexpectedException ('top n record DAO failure'), failing OAP startup.","triggerScenarios":"Declaring a custom TopN stream whose builder class cannot be reflectively instantiated with newInstance(); storage plugin jar incompatibility making the DAO creation path fail.","commonSituations":"Custom top-N (e.g. service slow endpoint tracking) plugins with incorrect builder declarations; mixing OAP versions between server-core and a custom storage extension.","solutions":["Add a public no-arg constructor to the builder class named in the @Stream annotation (most common cause: only a parameterized constructor exists)","Make sure the class is public and non-abstract and implements StorageBuilder","Rebuild the plugin against the current OAP version and verify a single plugin version in oap-libs"],"exampleFix":"// before\npublic static class TopNBuilder implements StorageBuilder {\n    public TopNBuilder(int size) {}\n}\n// after\npublic static class TopNBuilder implements StorageBuilder {\n    public TopNBuilder() {}\n}","handlingStrategy":"try-catch","validationCode":"assertNotNull(MyTopN.Builder.class.getDeclaredConstructor());\nassertTrue(StorageBuilder.class.isAssignableFrom(MyTopN.Builder.class));","typeGuard":null,"tryCatchPattern":"Fail fast at startup; in test code catch UnexpectedException, unwrap getCause(), and fail with a message naming the builder class defect.","preventionTips":["Reuse the stock TopN builder pattern (public no-arg constructor) for custom top-N streams","Verify plugin compatibility after OAP upgrades with a local boot before rollout","Automate a 'starts clean' check in the deployment pipeline"],"tags":["stream-processor","storage","reflection","startup","topn","plugin"],"backgroundTag":null,"analyzedSha":"102af09b4a56064e22050dded10e2c52e490d040","analyzedAt":"2026-08-14T10:47:52.647Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}