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

Register the missing teardown in the task configuration: restTestsTask.getTeardowns().put('someName', teardownBody).

elastic/elasticsearch · error · InvalidUserDataException

Couldn't find named teardown $name for ${snippet}

Error message

Couldn't find named teardown $name for ${snippet}

What it means

TestBuilder.teardown iterates the comma-separated names in snippet.teardown() and looks each up in the teardowns MapProperty (getTeardowns().get()). If a name is not a key in that map, no teardown body exists to insert, so it throws. Note the message literally contains the text '$name' (un-interpolated) because the source uses string concatenation of the variable 'name' but the message template wrote the literal '$name' — the actual missing name is appended after 'for ' via the snippet toString.

Source

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

            if (test.teardown() != null) {
                teardown(test);
            }
        }

        private void response(Snippet response) {
            if (null == response.skip()) {
                current.println("  - match:");
                current.println("      $body:");
                replaceBlockQuote(response.contents()).lines().forEach(line -> current.println("        " + line));
            }
        }

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

        private void testTearDown(Snippet snippet) {
            if (previousTest != null && previousTest.testSetup() == false && lastDocsPath.equals(snippet.path())) {
                throw new InvalidUserDataException(snippet + " must follow test setup or be first");
            }
            setupCurrent(snippet);
            current.println("---");
            current.println("teardown:");
            body(snippet, true);
        }

        void emitDo(
            String method,

View on GitHub (pinned to db6a809a66)

Solutions

Register the missing teardown in the task configuration: restTestsTask.getTeardowns().put('someName', teardownBody).
Fix the spelling of the name in the doc snippet to match the registered key exactly.
Remove the // TEARDOWN[someName] reference from the doc if the teardown is no longer needed.

Example fix

// before — doc references an unregistered teardown
// CONSOLE
// TEARDOWN[cleanup]
GET /_search

// build.gradle (missing registration)

// after — register in build.gradle
restTestsTask.getTeardowns().put('cleanup', '''
DELETE /idx
''')

Defensive patterns

Strategy: validation

Validate before calling

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

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

Prevention

Register every teardown name in build.gradle via getTeardowns().put(name, body).
Keep teardown names consistent between docs and build config — treat the registration as the source of truth.
When removing a teardown registration, grep the docs for references and remove them too.

When it happens

Trigger: A console snippet declares // TEARDOWN[someName] but the build did not register 'someName' in the teardowns MapProperty configured on the RestTestsFromDocSnippetTask.

Common situations: Typo in the teardown name between the doc and the build.gradle registration; removing a teardown registration from the build while the doc still references it; adding a new TEARDOWN reference without registering it.

Related errors

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