{"record":{"id":"db227ac38cebd3ae","repo":"elastic/elasticsearch","slug":"unsupported-file-type-docfilename","errorCode":null,"errorMessage":"Unsupported file type: ${docFileName}","messagePattern":"Unsupported file type: (.+?)","errorType":"validation","errorClass":"InvalidUserDataException","httpStatus":null,"severity":"error","filePath":"build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/DocSnippetTask.java","lineNumber":75,"sourceCode":"            List<Snippet> snippets = parseDocFile(docs.getDir(), file);\n            if (perSnippet != null) {\n                snippets.forEach(perSnippet::execute);\n            }\n        }\n    }\n\n    List<Snippet> parseDocFile(File rootDir, File docFile) {\n        SnippetParser parser = parserForFileType(docFile);\n        return parser.parseDoc(rootDir, docFile);\n    }\n\n    private SnippetParser parserForFileType(File docFile) {\n        if (docFile.getName().endsWith(\".asciidoc\")) {\n            return new AsciidocSnippetParser(getDefaultSubstitutions().get());\n        } else if (docFile.getName().endsWith(\".mdx\")) {\n            return new MdxSnippetParser(getDefaultSubstitutions().get());\n        }\n        throw new InvalidUserDataException(\"Unsupported file type: \" + docFile.getName());\n    }\n\n    public void setPerSnippet(Action<Snippet> perSnippet) {\n        this.perSnippet = perSnippet;\n    }\n\n}\n","sourceCodeStart":57,"sourceCodeEnd":83,"githubUrl":"https://github.com/elastic/elasticsearch/blob/db6a809a667c081ca1dc7500389d26975573215f/build-tools-internal/src/main/java/org/elasticsearch/gradle/internal/doc/DocSnippetTask.java#L57-L83","documentation":"DocSnippetTask.parserForFileType only knows how to parse '.asciidoc' and '.mdx' files. Any file passed to the docs FileTree with a different extension falls through both branches and hits this terminal throw, because no SnippetParser implementation exists for that format.","triggerScenarios":"The docs ConfigurableFileTree includes a file whose name does not end in '.asciidoc' or '.mdx' (e.g. a '.adoc', '.md', '.html', '.txt', or a backup '.asciidoc.bak' file), and executeTask iterates over it.","commonSituations":"Using '.adoc' instead of '.asciidoc' (a common AsciiDoc shorthand), leaving a '.bak' or '~' backup file in the docs source directory, or configuring a docs FileTree glob that accidentally sweeps up non-doc files like README.md or build artifacts.","solutions":["Rename or remove the offending file so it ends in '.asciidoc' or '.mdx'.","Restrict the docs FileTree include pattern to '**/*.asciidoc' and '**/*.mdx' so non-doc files are excluded.","If '.adoc' must be supported, add a branch in parserForFileType returning AsciidocSnippetParser for '.adoc' as well (requires modifying build-tools-internal)."],"exampleFix":"// before: docs tree sweeps all files\nsetDocs(getProject().fileTree(\"docs/setups\"))\n\n// after: restrict to supported extensions\nsetDocs(getProject().fileTree(\"docs/setups\", t -> {\n    t.include(\"**/*.asciidoc\");\n    t.include(\"**/*.mdx\");\n}))","handlingStrategy":"type-guard","validationCode":"// Validate docs FileTree contents before the task runs\nimport java.io.File;\nimport java.util.Arrays;\nimport java.util.List;\n\nvoid checkDocExtensions(File docsDir) {\n    List<String> allowed = List.of(\".asciidoc\", \".mdx\");\n    File[] bad = docsDir.listFiles(f ->\n        f.isFile() && allowed.stream().noneMatch(ext -> f.getName().endsWith(ext)));\n    if (bad != null && bad.length > 0) {\n        throw new IllegalStateException(\"Unsupported doc files (must be .asciidoc/.mdx): \"\n            + Arrays.toString(bad));\n    }\n}","typeGuard":"// Type guard for a single doc file\nboolean isSupportedDocFile(File f) {\n    String n = f.getName();\n    return n.endsWith(\".asciidoc\") || n.endsWith(\".mdx\");\n}","tryCatchPattern":null,"preventionTips":["Always scope the docs FileTree with explicit include patterns ('**/*.asciidoc', '**/*.mdx').","Keep backup files (*.bak, *~) out of the docs source tree.","Standardize on '.asciidoc' (not '.adoc') across the project."],"tags":["docs","asciidoc","mdx","file-type","gradle"],"backgroundTag":null,"analyzedSha":"db6a809a667c081ca1dc7500389d26975573215f","analyzedAt":"2026-08-12T01:39:14.192Z","schemaVersion":2},"datasetVersion":"2026-08-12T12:31:55.035Z"}