elastic/elasticsearch · error · InvalidUserDataException

Unsupported file type: ${docFileName}

Error message

Unsupported file type: ${docFileName}

What it means

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.

Source

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

            List<Snippet> snippets = parseDocFile(docs.getDir(), file);
            if (perSnippet != null) {
                snippets.forEach(perSnippet::execute);
            }
        }
    }

    List<Snippet> parseDocFile(File rootDir, File docFile) {
        SnippetParser parser = parserForFileType(docFile);
        return parser.parseDoc(rootDir, docFile);
    }

    private SnippetParser parserForFileType(File docFile) {
        if (docFile.getName().endsWith(".asciidoc")) {
            return new AsciidocSnippetParser(getDefaultSubstitutions().get());
        } else if (docFile.getName().endsWith(".mdx")) {
            return new MdxSnippetParser(getDefaultSubstitutions().get());
        }
        throw new InvalidUserDataException("Unsupported file type: " + docFile.getName());
    }

    public void setPerSnippet(Action<Snippet> perSnippet) {
        this.perSnippet = perSnippet;
    }

}

View on GitHub (pinned to db6a809a66)

Solutions

1. Rename or remove the offending file so it ends in '.asciidoc' or '.mdx'.
2. Restrict the docs FileTree include pattern to '**/*.asciidoc' and '**/*.mdx' so non-doc files are excluded.
3. If '.adoc' must be supported, add a branch in parserForFileType returning AsciidocSnippetParser for '.adoc' as well (requires modifying build-tools-internal).

Example fix

// before: docs tree sweeps all files
setDocs(getProject().fileTree("docs/setups"))

// after: restrict to supported extensions
setDocs(getProject().fileTree("docs/setups", t -> {
    t.include("**/*.asciidoc");
    t.include("**/*.mdx");
}))

// Validate docs FileTree contents before the task runs
import java.io.File;
import java.util.Arrays;
import java.util.List;

void checkDocExtensions(File docsDir) {
    List<String> allowed = List.of(".asciidoc", ".mdx");
    File[] bad = docsDir.listFiles(f ->
        f.isFile() && allowed.stream().noneMatch(ext -> f.getName().endsWith(ext)));
    if (bad != null && bad.length > 0) {
        throw new IllegalStateException("Unsupported doc files (must be .asciidoc/.mdx): "
            + Arrays.toString(bad));
    }
}

// Type guard for a single doc file
boolean isSupportedDocFile(File f) {
    String n = f.getName();
    return n.endsWith(".asciidoc") || n.endsWith(".mdx");
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Found multiple files with the same name '${fileNameWithoutEx
• ${snippet}: Use `js` instead of `${snippetLanguage}`.
• Couldn't find named teardown $name for ${snippet}
• Couldn't find named setup {name} for {snippet}
• Expected unconverted snippets but none found in: {listedButN

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