{"record":{"id":"b1f4a8182fe351d2","repo":"elastic/elasticsearch","slug":"unexpected-unconverted-snippets-foundbutnotliste","errorCode":null,"errorMessage":"Unexpected unconverted snippets:\n{foundButNotListed}","messagePattern":"Unexpected unconverted snippets:\n(.+?)","errorType":"validation","errorClass":"InvalidUserDataException","httpStatus":null,"severity":"error","filePath":"build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java","lineNumber":503,"sourceCode":"            String message = \"\";\n            if (false == listedButNotFound.isEmpty()) {\n                Collections.sort(listedButNotFound);\n                listedButNotFound = listedButNotFound.stream().map(notfound -> \"    \" + notfound).collect(Collectors.toList());\n                message += \"Expected unconverted snippets but none found in:\\n\";\n                message += listedButNotFound.stream().collect(Collectors.joining(\"\\n\"));\n            }\n            if (false == unconvertedCandidates.isEmpty()) {\n                List<String> foundButNotListed = new ArrayList<>(unconvertedCandidates);\n                Collections.sort(foundButNotListed);\n                foundButNotListed = foundButNotListed.stream().map(f -> \"    \" + f).collect(Collectors.toList());\n                if (false == \"\".equals(message)) {\n                    message += \"\\n\";\n                }\n                message += \"Unexpected unconverted snippets:\\n\";\n                message += foundButNotListed.stream().collect(Collectors.joining(\"\\n\"));\n            }\n            if (false == \"\".equals(message)) {\n                throw new InvalidUserDataException(message);\n            }\n        }\n\n        public void finishLastTest() {\n            if (current != null) {\n                current.close();\n                current = null;\n            }\n        }\n    }\n\n    private void assertEqualTestSnippetFromMigratedDocs() {\n        getTestRoot().getAsFileTree().matching(patternSet -> { patternSet.include(\"**/*asciidoc.yml\"); }).forEach(asciidocFile -> {\n            File mdxFile = new File(asciidocFile.getAbsolutePath().replace(\".asciidoc.yml\", \".mdx.yml\"));\n            if (mdxFile.exists() == false) {\n                throw new InvalidUserDataException(\"Couldn't find the corresponding mdx file for \" + asciidocFile.getAbsolutePath());\n            }\n            try {","sourceCodeStart":485,"sourceCodeEnd":521,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java#L485-L521","documentation":"Thrown by RestTestsFromDocSnippetTask after parsing all documentation snippets when the set of snippets discovered in docs does not match the set registered as 'converted' (i.e. expected to be turned into REST tests). The task collects any candidate snippets that were found but not listed as expected, sorts them, and fails the build with the full list so the author knows exactly which snippets are unaccounted for. It exists to prevent documentation examples from silently shipping without a corresponding test.","triggerScenarios":"Build runs the doc-snippet REST test generation task (e.g. `:docs:check` or a `RestTestsFromDoc*Task`). A new `// CONSOLE` or test snippet was added to an asciidoc/mdx doc file but was never added to the list of converted/expected snippets that the task maintains. Conversely, a snippet was removed from docs but its entry remains in the converted list (the symmetric diff manifests as 'found but not listed').","commonSituations":"A contributor adds a new example block to documentation and forgets to register it; an asciidoc-to-mdx migration leaves an orphaned snippet reference; a doc rename changes the snippet path so the old entry no longer matches.","solutions":["Read the listed snippet paths in the error message and for each one either add a corresponding test snippet registration in the docs build config or remove the snippet from the source documentation file.","If you intentionally removed a snippet, delete its entry from the converted-snippets list so both sets agree.","Re-run the specific task with `--info` to see which doc file each unconverted snippet originated from."],"exampleFix":"// before: doc contains a CONSOLE snippet not registered\n// after: add the snippet to the converted list, or remove the snippet block from the ascidoc","handlingStrategy":"validation","validationCode":"// Before running the doc test task, assert the set of discovered snippets\n// equals the set of registered/converted snippets (run a dry diff locally):\n//   collect discovered snippet paths from doc sources\n//   collect converted snippet paths from the task config\n//   Collections.disjoint(discovered, converted) -> list and fix before building","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Whenever you add or remove a `// CONSOLE` snippet in docs, immediately update the converted-snippets list in the same commit.","Run the doc REST test task locally before pushing (`./gradlew :docs:check` or equivalent).","Treat any snippet-path rename as a two-file change: the doc and the converted list."],"tags":["docs","snippet-tests","build","validation"],"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T08:17:17.861Z"}