{"record":{"id":"b1aa36a65a7e0f0a","repo":"elastic/elasticsearch","slug":"couldn-t-find-named-setup-name-for-snippet","errorCode":null,"errorMessage":"Couldn't find named setup {name} for {snippet}","messagePattern":"Couldn't find named setup (.+?) for (.+?)","errorType":"validation","errorClass":"InvalidUserDataException","httpStatus":null,"severity":"error","filePath":"build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java","lineNumber":471,"sourceCode":"                throw new InvalidUserDataException(\n                    snippet + \": wasn't first. TESTSETUP can only be used in the first snippet of a document.\"\n                );\n            }\n            setupCurrent(snippet);\n            current.println(\"---\");\n            current.println(\"setup:\");\n            if (snippet.setup() != null) {\n                setup(snippet);\n            }\n            body(snippet, true);\n        }\n\n        private void setup(final Snippet snippet) {\n            // insert a setup defined outside of the docs\n            for (final String name : snippet.setup().split(\",\")) {\n                final String setup = getSetups().get(name);\n                if (setup == null) {\n                    throw new InvalidUserDataException(\"Couldn't find named setup \" + name + \" for \" + snippet);\n                }\n                current.println(\"# Named setup \" + name);\n                current.println(setup);\n            }\n        }\n\n        public void checkUnconverted() {\n            List<String> listedButNotFound = new ArrayList<>();\n            for (String listed : getExpectedUnconvertedCandidates().get()) {\n                if (false == unconvertedCandidates.remove(listed)) {\n                    listedButNotFound.add(listed);\n                }\n            }\n            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\";","sourceCodeStart":453,"sourceCodeEnd":489,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java#L453-L489","documentation":"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.","triggerScenarios":"A console snippet declares // SETUP[bootstrap] but 'bootstrap' was never registered via restTestsTask.getSetups().put('bootstrap', body) in the Gradle build script.","commonSituations":"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.","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."],"exampleFix":"// before — doc references an unregistered setup\n// CONSOLE\n// SETUP[bootstrap]\nGET /_search\n\n// after — register in build.gradle\nrestTestsTask.getSetups().put('bootstrap', '''\nPOST /idx/_doc\n{\"a\":1}\n''')","handlingStrategy":"validation","validationCode":"// Verify every setup name referenced in docs is registered in the build\nimport java.util.Map;\nimport java.util.Arrays;\n\nvoid checkSetupsRegistered(List<SnippetInfo> snippets, Map<String,String> registered) {\n    for (SnippetInfo s : snippets) {\n        if (s.setup != null) {\n            for (String name : s.setup.split(\",\")) {\n                if (!registered.containsKey(name.trim())) {\n                    throw new IllegalStateException(\n                        \"Setup '\" + name + \"' in \" + s.path + \" is not registered. \"\n                        + \"Add: restTestsTask.getSetups().put('\" + name + \"', <body>)\");\n                }\n            }\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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."],"tags":["docs","setup","named","registration","gradle"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}