elastic/elasticsearch · error · InvalidUserDataException

${snippet}: Use `js` instead of `${snippetLanguage}`.

Error message

${snippet}: Use `js` instead of `${snippetLanguage}`.

What it means

TestBuilder.BAD_LANGUAGES lists 'json' and 'javascript' as unsupported by the documentation syntax highlighter. When a snippet's language attribute matches one of these, handleSnippet throws, instructing the author to use 'js' instead — the supported equivalent that renders correctly in the docs site.

Source

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

        Path lastDocsPath;

        /**
         * The file we're building.
         */
        PrintWriter current;

        Set<String> names = new HashSet<>();

        /**
         * Called each time a snippet is encountered. Tracks the snippets and
         * calls buildTest to actually build the test.
         */
        public void handleSnippet(Snippet snippet) {
            if (snippet.isConsoleCandidate()) {
                unconvertedCandidates.add(snippet.path().toString().replace('\\', '/'));
            }
            if (BAD_LANGUAGES.contains(snippet.language())) {
                throw new InvalidUserDataException(snippet + ": Use `js` instead of `" + snippet.language() + "`.");
            }
            if (snippet.testSetup()) {
                testSetup(snippet);
                previousTest = snippet;
                return;
            }
            if (snippet.testTearDown()) {
                testTearDown(snippet);
                previousTest = snippet;
                return;
            }
            if (snippet.testResponse() || snippet.language().equals("console-result")) {
                if (previousTest == null) {
                    throw new InvalidUserDataException(snippet + ": No paired previous test");
                }
                if (previousTest.path().equals(snippet.path()) == false) {
                    throw new InvalidUserDataException(snippet + ": Result can't be first in file");
                }

View on GitHub (pinned to db6a809a66)

Solutions

1. Change the source block language from 'json' or 'javascript' to 'js'.
2. If the block is a JSON response example, use 'js' with the console-result snippet type as needed.

Example fix

// before (asciidoc)
[source,json]
----
{ "status": "ok" }
----

// after
[source,js]
----
{ "status": "ok" }
----

// Reject unsupported snippet languages before the build
import java.util.Set;
import java.util.List;

private static final Set<String> BAD = Set.of("json", "javascript");

void checkSnippetLanguage(String language, String snippetPath) {
    if (BAD.contains(language)) {
        throw new IllegalStateException(
            "Snippet in " + snippetPath + " uses '" + language
            + "'. Use 'js' instead.");
    }
}

boolean isSupportedLanguage(String lang) {
    return !Set.of("json", "javascript").contains(lang);
}

When it happens

Trigger: A source block in an asciidoc or mdx doc is annotated with [source,json] or [source,javascript] (or the mdx equivalent language tag), and the snippet is processed by the DocSnippetTask.

Common situations: Copying a code block from an external source that uses 'json'/'javascript' as the language identifier; muscle memory from other doc systems that accept those names. The docs infrastructure only has a highlighter registered for 'js'.

Related errors

• Unsupported file type: ${docFileName}
• ${snippet}: Use `[source,console]` instead of `// CONSOLE`.
• Found multiple files with the same name '${fileNameWithoutEx
• Extra content ${message} ('${cutOutNoNl}') matching [${patte
• Didn't match ${pattern}: ${content}

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