What causes "Unexpected unconverted snippets: {foundButNotListed}" in elastic/elasticsearch?

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.

elastic/elasticsearch · error · InvalidUserDataException

Unexpected unconverted snippets: {foundButNotListed}

Error message

Unexpected unconverted snippets:
{foundButNotListed}

What it means

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.

Source

Thrown at build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java:503

            String message = "";
            if (false == listedButNotFound.isEmpty()) {
                Collections.sort(listedButNotFound);
                listedButNotFound = listedButNotFound.stream().map(notfound -> "    " + notfound).collect(Collectors.toList());
                message += "Expected unconverted snippets but none found in:\n";
                message += listedButNotFound.stream().collect(Collectors.joining("\n"));
            }
            if (false == unconvertedCandidates.isEmpty()) {
                List<String> foundButNotListed = new ArrayList<>(unconvertedCandidates);
                Collections.sort(foundButNotListed);
                foundButNotListed = foundButNotListed.stream().map(f -> "    " + f).collect(Collectors.toList());
                if (false == "".equals(message)) {
                    message += "\n";
                }
                message += "Unexpected unconverted snippets:\n";
                message += foundButNotListed.stream().collect(Collectors.joining("\n"));
            }
            if (false == "".equals(message)) {
                throw new InvalidUserDataException(message);
            }
        }

        public void finishLastTest() {
            if (current != null) {
                current.close();
                current = null;
            }
        }
    }

    private void assertEqualTestSnippetFromMigratedDocs() {
        getTestRoot().getAsFileTree().matching(patternSet -> { patternSet.include("**/*asciidoc.yml"); }).forEach(asciidocFile -> {
            File mdxFile = new File(asciidocFile.getAbsolutePath().replace(".asciidoc.yml", ".mdx.yml"));
            if (mdxFile.exists() == false) {
                throw new InvalidUserDataException("Couldn't find the corresponding mdx file for " + asciidocFile.getAbsolutePath());
            }
            try {

View on GitHub (pinned to db6a809a66)

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.

Example fix

// before: doc contains a CONSOLE snippet not registered
// after: add the snippet to the converted list, or remove the snippet block from the ascidoc

Defensive patterns

Strategy: validation

Validate before calling

// Before running the doc test task, assert the set of discovered snippets
// equals the set of registered/converted snippets (run a dry diff locally):
//   collect discovered snippet paths from doc sources
//   collect converted snippet paths from the task config
//   Collections.disjoint(discovered, converted) -> list and fix before building

Prevention

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.

When it happens

Trigger: 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').

Common situations: 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.

Related errors

AI-assisted analysis of elastic/elasticsearch@db6a809a66 (2026-08-12). Data as JSON: /api/errors/b1f4a8182fe351d2. Report an issue: GitHub.