{"record":{"id":"988736427e4d0463","repo":"elastic/elasticsearch","slug":"snippet-use-js-instead-of-snippetlanguage","errorCode":null,"errorMessage":"${snippet}: Use `js` instead of `${snippetLanguage}`.","messagePattern":"(.+?): Use `js` instead of `(.+?)`\\.","errorType":"validation","errorClass":"InvalidUserDataException","httpStatus":null,"severity":"error","filePath":"build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java","lineNumber":206,"sourceCode":"        Path lastDocsPath;\n\n        /**\n         * The file we're building.\n         */\n        PrintWriter current;\n\n        Set<String> names = new HashSet<>();\n\n        /**\n         * Called each time a snippet is encountered. Tracks the snippets and\n         * calls buildTest to actually build the test.\n         */\n        public void handleSnippet(Snippet snippet) {\n            if (snippet.isConsoleCandidate()) {\n                unconvertedCandidates.add(snippet.path().toString().replace('\\\\', '/'));\n            }\n            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                }","sourceCodeStart":188,"sourceCodeEnd":224,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/RestTestsFromDocSnippetTask.java#L188-L224","documentation":"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.","triggerScenarios":"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.","commonSituations":"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'.","solutions":["Change the source block language from 'json' or 'javascript' to 'js'.","If the block is a JSON response example, use 'js' with the console-result snippet type as needed."],"exampleFix":"// before (asciidoc)\n[source,json]\n----\n{ \"status\": \"ok\" }\n----\n\n// after\n[source,js]\n----\n{ \"status\": \"ok\" }\n----","handlingStrategy":"type-guard","validationCode":"// Reject unsupported snippet languages before the build\nimport java.util.Set;\nimport java.util.List;\n\nprivate static final Set<String> BAD = Set.of(\"json\", \"javascript\");\n\nvoid checkSnippetLanguage(String language, String snippetPath) {\n    if (BAD.contains(language)) {\n        throw new IllegalStateException(\n            \"Snippet in \" + snippetPath + \" uses '\" + language\n            + \"'. Use 'js' instead.\");\n    }\n}","typeGuard":"boolean isSupportedLanguage(String lang) {\n    return !Set.of(\"json\", \"javascript\").contains(lang);\n}","tryCatchPattern":null,"preventionTips":["Only use 'js' for JavaScript/JSON source blocks in docs.","Add a grep-based CI check: grep -rn '\\[source,json\\]\\|\\[source,javascript\\]' docs/ should return nothing.","When pasting examples from elsewhere, rewrite the language tag to 'js'."],"tags":["docs","snippet","language","syntax-highlighting","asciidoc","mdx"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T13:17:24.610Z"}