elastic/elasticsearch · error · InvalidUserDataException

CONSOLE not paired with a snippet

Error message

CONSOLE not paired with a snippet

What it means

Thrown by SnippetParser.consoleHandled() when a line matching the CONSOLE regex (e.g. `// CONSOLE`) is encountered but snippetBuilder is null — meaning there is no open snippet to mark as a console example. The CONSOLE directive's purpose is to flag the preceding/current snippet as a console (curl-style) example, so it must be associated with an active snippet.

Source

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

                        snippetBuilder.withWarning(m.group(8));
                        return;
                    }
                    if (m.group(9) != null) {
                        snippetBuilder.withSkipShardsFailures(true);
                        return;
                    }
                    throw new InvalidUserDataException("Invalid test marker: " + line);
                });
            }
            return true;
        }
        return false;
    }

    protected boolean consoleHandled(String line, SnippetBuilder snippet) {
        if (line.matches(getConsoleRegex())) {
            if (snippetBuilder == null) {
                throw new InvalidUserDataException("CONSOLE not paired with a snippet");
            }
            if (snippetBuilder.consoleDefined()) {
                throw new InvalidUserDataException("Can't be both CONSOLE and NOTCONSOLE");
            }
            snippetBuilder.withConsole(Boolean.TRUE);
            return true;
        } else if (line.matches(getNotconsoleRegex())) {
            if (snippet == null) {
                throw new InvalidUserDataException("NOTCONSOLE not paired with a snippet");
            }
            if (snippetBuilder.consoleDefined()) {
                throw new InvalidUserDataException("Can't be both CONSOLE and NOTCONSOLE");
            }
            snippet.withConsole(Boolean.FALSE);
            return true;
        }
        return false;
    }

View on GitHub (pinned to db6a809a66)

Solutions

1. Ensure the `// CONSOLE` directive is positioned with an open snippet (a source code block) it can attach to — typically directly above or below the snippet per the doc format's convention.
2. Remove the orphaned `// CONSOLE` line if its snippet was deleted.
3. Verify the snippet-opening syntax is correct so the parser actually opens a snippet before reaching the CONSOLE marker.

Example fix

// before:
// CONSOLE
// (no source block)
// after:
// CONSOLE
----
GET /_search
----

// Before building, walk doc lines and ensure every // CONSOLE has an open snippet to attach to.

When it happens

Trigger: A `// CONSOLE` line appears in a doc file with no currently-open snippet (snippetBuilder is null). The getConsoleRegex matches and the guard fires.

Common situations: A CONSOLE marker is placed where there is no source block before it; the preceding snippet was closed before the marker; a copy-paste left a stray `// CONSOLE` with no associated code block.

Related errors

• Unexpected unconverted snippets: {foundButNotListed}
• Couldn't find the corresponding mdx file for {asciidocFileAb
• Yaml rest specs ({asciidocFile} and {mdxFile}) are not equal
• Yaml rest specs ({asciidocFile} and {mdxFile}) are not equal
• {name}: Snippet missing a language. This is required by Elas

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