elastic/elasticsearch · error · InvalidUserDataException

Unsupported file type

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.

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
• : Use `js` instead of ` `.
• Couldn't find named setup
• Couldn't find named teardown $name for
• Expected unconverted snippets but none found in

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

Appendix: 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)