What causes "// TEST[continued] cannot be on first snippet in a file: ${test}" in elastic/elasticsearch?

Ensure a non-continued console request snippet precedes the // TEST[continued] snippet in the same file.

elastic/elasticsearch · error · InvalidUserDataException

// TEST[continued] cannot be on first snippet in a file: ${t

Error message

// TEST[continued] cannot be on first snippet in a file: ${test}

What it means

In TestBuilder.test, if a snippet is marked // TEST[continued], it must extend a previous test in the same file (previousTest != null AND same path). 'continued' appends to the previous test's YAML section rather than starting a new one, so there must be a prior request to continue. If previousTest is null or in a different file, continuation is impossible.

Source

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

            }
            if (("js".equals(snippet.language())) && snippet.console() != null && snippet.console()) {
                throw new InvalidUserDataException(snippet + ": Use `[source,console]` instead of `// CONSOLE`.");
            }
            if (snippet.test() || snippet.language().equals("console")) {
                test(snippet);
                previousTest = snippet;
            }
            // Must be an unmarked snippet....
        }

        private void test(Snippet test) {
            setupCurrent(test);

            if (test.continued()) {
                /* Catch some difficult to debug errors with // TEST[continued]
                 * and throw a helpful error message. */
                if (previousTest == null || previousTest.path().equals(test.path()) == false) {
                    throw new InvalidUserDataException("// TEST[continued] " + "cannot be on first snippet in a file: " + test);
                }
                if (previousTest != null && previousTest.testSetup()) {
                    throw new InvalidUserDataException("// TEST[continued] " + "cannot immediately follow // TESTSETUP: " + test);
                }
                if (previousTest != null && previousTest.testSetup()) {
                    throw new InvalidUserDataException("// TEST[continued] " + "cannot immediately follow // TEARDOWN: " + test);
                }
            } else {
                current.println("---");
                if (test.name() != null && test.name().isBlank() == false) {
                    if (names.add(test.name()) == false) {
                        throw new InvalidUserDataException("Duplicated snippet name '" + test.name() + "': " + test);
                    }
                    current.println("\"" + test.name() + "\":");
                } else {
                    current.println("\"line_" + test.start() + "\":");
                }
                /* The Elasticsearch test runner doesn't support quite a few

View on GitHub (pinned to db6a809a66)

Solutions

Ensure a non-continued console request snippet precedes the // TEST[continued] snippet in the same file.
Remove // TEST[continued] from the first snippet if it is meant to be a standalone test.

Example fix

// before — continued is the first snippet
// CONSOLE
// TEST[continued]
GET /_search

// after — add a base request first
// CONSOLE
POST /idx/_doc
{ "a": 1 }
// CONSOLE
// TEST[continued]
GET /idx/_search

Defensive patterns

Strategy: validation

Validate before calling

// Ensure TEST[continued] is never the first test snippet in a file
void checkContinuedNotFirst(List<SnippetInfo> fileSnippets, String filePath) {
    boolean seenBase = false;
    for (SnippetInfo s : fileSnippets) {
        if (s.continued && !seenBase) {
            throw new IllegalStateException(
                "// TEST[continued] in " + filePath + " has no preceding base request");
        }
        if (s.isRequest && !s.continued) seenBase = true;
    }
}

Prevention

Always write a non-continued console request before any // TEST[continued] snippet in the same file.
When moving snippets between files, ensure a continued snippet's base request travels with it.
Treat a file whose first test snippet is 'continued' as a lint failure.

When it happens

Trigger: The first executable snippet in a doc file carries // TEST[continued], or a continued snippet appears in a file whose previous test was in a different file.

Common situations: Adding a new // TEST[continued] block at the top of a file before writing the initial request, or moving a continued snippet to a new file without its base request.

Related errors

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