elastic/elasticsearch · error · InvalidUserDataException

{name}: Snippet missing a language. This is required by Elas

Error message

{name}: Snippet missing a language. This is required by Elasticsearch's doc testing infrastructure so we be sure we don't accidentally forget to test a snippet.

What it means

Thrown by SnippetBuilder.validate() when a documentation code snippet was started (e.g. a `// CONSOLE` block) but no programming language was assigned before the snippet was finalized. The doc-testing infrastructure requires every snippet to declare a language so it can route it to the correct syntax validation and test harness; a missing language means the snippet could silently skip being tested.

Source

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

            testResponse,
            testSetup,
            testTeardown,
            skip,
            continued,
            language,
            catchPart,
            setup,
            teardown,
            curl,
            warnings,
            skipShardsFailures,
            name
        );
    }

    public void validate(String content) {
        if (language == null) {
            throw new InvalidUserDataException(
                name
                    + ": "
                    + "Snippet missing a language. This is required by "
                    + "Elasticsearch's doc testing infrastructure so we "
                    + "be sure we don't accidentally forget to test a "
                    + "snippet."
            );
        }
        assertValidCurlInput(content);
        assertValidJsonInput(content);

    }

    private void assertValidCurlInput(String content) {
        // Try to detect snippets that contain `curl`
        if ("sh".equals(language) || "shell".equals(language)) {
            curl = content.contains("curl");
            if (console == Boolean.FALSE && curl == false) {

View on GitHub (pinned to db6a809a66)

Solutions

Add the language attribute to the source block in the doc file (e.g. `[source,json]` for asciidoc or the appropriate markdown/mdx fenced-code language tag).
Confirm the language directive the parser expects for your doc format — asciidoc and mdx use different conventions.
Re-run the doc test task for just the affected file to confirm the snippet now validates.

Example fix

// before (asciidoc):
// CONSOLE
GET /_search
// after:
[source,json]
// CONSOLE
GET /_search

Defensive patterns

Strategy: validation

Validate before calling

// Before building, assert every snippet block declares a language:
// for each snippet: if (snippet.language == null) fail(name + " missing language");

Prevention

Always annotate source blocks with a language ([source,json] in asciidoc, fenced ```json in mdx).
Use editor snippets/templates that include the language by default.
Run the doc snippet validation task locally before pushing.

When it happens

Trigger: A snippet block is opened with a marker like `// CONSOLE` or `// NOTCONSOLE` but the underlying asciidoc/mdx source never specified the snippet's language (typically via the source block's language attribute or a `// <lang>` directive, depending on the parser dialect). When SnippetBuilder.build()→validate() runs, `language` is still null.

Common situations: A doc author writes a new example block and forgets the language annotation; an asciidoc `[source,json]` attribute was typo'd or stripped during a format conversion; a snippet was copy-pasted from a non-source context.

Related errors

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