{"record":{"id":"0829216ecf2c6510","repo":"elastic/elasticsearch","slug":"snippet-result-can-t-be-first-in-file","errorCode":null,"errorMessage":"${snippet}: Result can't be first in file","messagePattern":"(.+?): Result can't be first in file","errorType":"validation","errorClass":"InvalidUserDataException","httpStatus":null,"severity":"error","filePath":"build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java","lineNumber":223,"sourceCode":"            if (BAD_LANGUAGES.contains(snippet.language())) {\n                throw new InvalidUserDataException(snippet + \": Use `js` instead of `\" + snippet.language() + \"`.\");\n            }\n            if (snippet.testSetup()) {\n                testSetup(snippet);\n                previousTest = snippet;\n                return;\n            }\n            if (snippet.testTearDown()) {\n                testTearDown(snippet);\n                previousTest = snippet;\n                return;\n            }\n            if (snippet.testResponse() || snippet.language().equals(\"console-result\")) {\n                if (previousTest == null) {\n                    throw new InvalidUserDataException(snippet + \": No paired previous test\");\n                }\n                if (previousTest.path().equals(snippet.path()) == false) {\n                    throw new InvalidUserDataException(snippet + \": Result can't be first in file\");\n                }\n                response(snippet);\n                return;\n            }\n            if ((\"js\".equals(snippet.language())) && snippet.console() != null && snippet.console()) {\n                throw new InvalidUserDataException(snippet + \": Use `[source,console]` instead of `// CONSOLE`.\");\n            }\n            if (snippet.test() || snippet.language().equals(\"console\")) {\n                test(snippet);\n                previousTest = snippet;\n            }\n            // Must be an unmarked snippet....\n        }\n\n        private void test(Snippet test) {\n            setupCurrent(test);\n\n            if (test.continued()) {","sourceCodeStart":205,"sourceCodeEnd":241,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java#L205-L241","documentation":"For a test-response snippet, after confirming previousTest is non-null, handleSnippet checks that previousTest lives in the same file as the response (previousTest.path().equals(snippet.path())). If they differ, the response is effectively the first test-related snippet in the current file with no paired request in-file, which the test runner cannot associate. The message 'Result can't be first in file' captures this cross-file orphan case.","triggerScenarios":"A console-result/TESTRESPONSE snippet is the first test snippet encountered in a document file, but a previousTest from a different file exists (so the null check passed but the path check fails).","commonSituations":"Splitting one asciidoc file into two and leaving the response block in the second file while its request stayed in the first; or copy-pasting a response block into a new file without its request.","solutions":["Move the paired console request snippet into the same file as the response, above it.","If the response belongs to a request in another file, remove the orphaned response from this file."],"exampleFix":"// file_b.asciidoc — before: response orphaned in a new file\n// TESTRESPONSE\n{\"hits\":{\"total\":0}}\n\n// after: bring the request into the same file\n// CONSOLE\nGET /my-index/_search\n// TESTRESPONSE\n{\"hits\":{\"total\":0}}","handlingStrategy":"validation","validationCode":"// Ensure response snippets share the same file as their paired request\nvoid checkResponseSameFile(List<SnippetInfo> snippets) {\n    String lastRequestFile = null;\n    for (SnippetInfo s : snippets) {\n        if (s.isRequest) lastRequestFile = s.filePath;\n        if (s.isResponse && !s.filePath.equals(lastRequestFile)) {\n            throw new IllegalStateException(\n                \"Response in \" + s.filePath + \" pairs with request in \" + lastRequestFile\n                + \" — they must be in the same file\");\n        }\n    }\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep request and response snippets in the same doc file.","When refactoring docs into multiple files, move request+response pairs together, never split them.","After file splits, run the docs build immediately to catch orphaned responses."],"tags":["docs","snippet","test-response","console","file-split"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}