What causes "Couldn't find named setup {name} for {snippet}" in elastic/elasticsearch?

Register the missing setup in the task configuration: restTestsTask.getSetups().put('bootstrap', setupBody).

elastic/elasticsearch · error · InvalidUserDataException

Couldn't find named setup {name} for {snippet}

Error message

Couldn't find named setup {name} for {snippet}

What it means

TestBuilder.setup iterates the comma-separated names in snippet.setup() and looks each up in the setups Map (getSetups().get(name)). If a name is absent, no setup body can be inserted and it throws. Unlike teardowns (a MapProperty), setups is a plain LinkedHashMap populated via getSetups().put(...) in build configuration.

Source

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

                throw new InvalidUserDataException(
                    snippet + ": wasn't first. TESTSETUP can only be used in the first snippet of a document."
                );
            }
            setupCurrent(snippet);
            current.println("---");
            current.println("setup:");
            if (snippet.setup() != null) {
                setup(snippet);
            }
            body(snippet, true);
        }

        private void setup(final Snippet snippet) {
            // insert a setup defined outside of the docs
            for (final String name : snippet.setup().split(",")) {
                final String setup = getSetups().get(name);
                if (setup == null) {
                    throw new InvalidUserDataException("Couldn't find named setup " + name + " for " + snippet);
                }
                current.println("# Named setup " + name);
                current.println(setup);
            }
        }

        public void checkUnconverted() {
            List<String> listedButNotFound = new ArrayList<>();
            for (String listed : getExpectedUnconvertedCandidates().get()) {
                if (false == unconvertedCandidates.remove(listed)) {
                    listedButNotFound.add(listed);
                }
            }
            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";

View on GitHub (pinned to db6a809a66)

Solutions

Register the missing setup in the task configuration: restTestsTask.getSetups().put('bootstrap', setupBody).
Correct the spelling of the name in the doc to match the registered key.
Remove the // SETUP[name] reference from the doc if it is no longer needed.

Example fix

// before — doc references an unregistered setup
// CONSOLE
// SETUP[bootstrap]
GET /_search

// after — register in build.gradle
restTestsTask.getSetups().put('bootstrap', '''
POST /idx/_doc
{"a":1}
''')

Defensive patterns

Strategy: validation

Validate before calling

// Verify every setup name referenced in docs is registered in the build
import java.util.Map;
import java.util.Arrays;

void checkSetupsRegistered(List<SnippetInfo> snippets, Map<String,String> registered) {
    for (SnippetInfo s : snippets) {
        if (s.setup != null) {
            for (String name : s.setup.split(",")) {
                if (!registered.containsKey(name.trim())) {
                    throw new IllegalStateException(
                        "Setup '" + name + "' in " + s.path + " is not registered. "
                        + "Add: restTestsTask.getSetups().put('" + name + "', <body>)");
                }
            }
        }
    }
}

Prevention

Register every setup name in build.gradle via getSetups().put(name, body).
Treat the build config as the source of truth for setup names; keep doc references in sync.
When removing a setup registration, grep the docs and remove all // SETUP[name] references to it.

When it happens

Trigger: A console snippet declares // SETUP[bootstrap] but 'bootstrap' was never registered via restTestsTask.getSetups().put('bootstrap', body) in the Gradle build script.

Common situations: Typo in the setup name, removing a setup registration from the build while docs still reference it, or adding a new SETUP reference without the matching registration.

Related errors

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