elastic/elasticsearch · error · InvalidUserDataException

Expected unconverted snippets but none found in: {listedButN

Error message

Expected unconverted snippets but none found in:
{listedButNotFound}

What it means

checkUnconverted runs at the end of the build. It maintains two sets: expected unconverted candidates (configured via getExpectedUnconvertedCandidates()) and actually-found unconverted candidates (snippets flagged isConsoleCandidate). The 'listed but not found' list collects every expected file that had no unconverted snippet. If that list is non-empty (and the found-but-not-listed list is empty), the combined message starts with this line, meaning a file was declared as still-containing-unconverted-snippets but all its snippets have actually been converted to console.

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

Remove the listed-but-not-found file path(s) (shown in the message) from the expectedUnconvertedCandidates configuration in build.gradle.
If a file was renamed, update the path in expectedUnconvertedCandidates to the new location or delete the stale entry.

Example fix

// before — allowlist still references a fully-converted file
restTestsTask.getExpectedUnconvertedCandidates().set(List.of(
    "setting-up/security.asciidoc",  // fully converted, no longer unconverted
    "ingest/pipelines.asciidoc"
))

// after — remove the converted file
restTestsTask.getExpectedUnconvertedCandidates().set(List.of(
    "ingest/pipelines.asciidoc"
))

Defensive patterns

Strategy: validation

Validate before calling

// Keep the expectedUnconvertedCandidates allowlist in sync with actual unconverted files
import java.nio.file.*;
import java.util.*;
import java.util.stream.*;

void checkExpectedUnconverted(File docsDir, List<String> expected) throws java.io.IOException {
    // expected = files that SHOULD still have unconverted snippets
    // (this lint is the inverse: confirm each expected file actually has a CONSOLE candidate)
    List<String> stale = new ArrayList<>();
    for (String rel : expected) {
        Path p = docsDir.toPath().resolve(rel);
        if (!Files.exists(p) || !Files.readString(p).contains("// CONSOLE")) {
            stale.add(rel);
        }
    }
    if (!stale.isEmpty()) {
        throw new IllegalStateException(
            "These files are fully converted but still in expectedUnconvertedCandidates: " + stale
            + ". Remove them from the list.");
    }
}

Prevention

When you finish converting a doc file's snippets to console, immediately remove it from expectedUnconvertedCandidates.
After renaming or moving a doc file, update the allowlist path accordingly.
Treat the build error message's file list as the exact set of entries to remove from the allowlist.

When it happens

Trigger: The expectedUnconvertedCandidates list property references a doc file path, but that file contains no console-candidate (unconverted) snippets — every snippet was already marked // CONSOLE or [source,console].

Common situations: An author finished converting a doc file's snippets to console but forgot to remove the file from the expectedUnconvertedCandidates allowlist in build.gradle; or the file path in the allowlist is stale after a rename/move.

Related errors

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