elastic/elasticsearch · error · InvalidUserDataException

Couldn't find the corresponding mdx file for {asciidocFileAb

Error message

Couldn't find the corresponding mdx file for {asciidocFileAbsolutePath}

What it means

Thrown during the asciidoc→mdx migration parity check (assertEqualTestSnippetFromMigratedDocs). For every `*.asciidoc.yml` REST spec file found under the test root, the task expects a sibling `*.mdx.yml` file to exist. If the mdx counterpart is missing, the build fails with the absolute path of the orphaned asciidoc file. This enforces a 1:1 mapping between the legacy asciidoc-based YAML REST specs and the migrated mdx-based ones.

Source

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

            }
            if (false == "".equals(message)) {
                throw new InvalidUserDataException(message);
            }
        }

        public void finishLastTest() {
            if (current != null) {
                current.close();
                current = null;
            }
        }
    }

    private void assertEqualTestSnippetFromMigratedDocs() {
        getTestRoot().getAsFileTree().matching(patternSet -> { patternSet.include("**/*asciidoc.yml"); }).forEach(asciidocFile -> {
            File mdxFile = new File(asciidocFile.getAbsolutePath().replace(".asciidoc.yml", ".mdx.yml"));
            if (mdxFile.exists() == false) {
                throw new InvalidUserDataException("Couldn't find the corresponding mdx file for " + asciidocFile.getAbsolutePath());
            }
            try {
                List<String> asciidocLines = Files.readAllLines(asciidocFile.toPath());
                List<String> mdxLines = Files.readAllLines(mdxFile.toPath());
                if (asciidocLines.size() != mdxLines.size()) {
                    throw new GradleException(
                        "Yaml rest specs ("
                            + asciidocFile.toPath()
                            + " and "
                            + mdxFile.getAbsolutePath()
                            + ") are not equal, different line count"
                    );

                }
                for (int i = 0; i < asciidocLines.size(); i++) {
                    if (asciidocLines.get(i)
                        .replaceAll("line_\\d+", "line_0")
                        .equals(mdxLines.get(i).replaceAll("line_\\d+", "line_0")) == false) {

View on GitHub (pinned to db6a809a66)

Solutions

1. Create the corresponding `<name>.mdx.yml` file next to the reported `<name>.asciidoc.yml` with the equivalent REST spec content.
2. If the asciidoc file is itself obsolete, delete it so only the mdx source of truth remains.
3. Verify the filename differs only by the `.asciidoc.yml` → `.mdx.yml` suffix (no extra dots or casing changes).

Example fix

# before: docs/set_settings.asciidoc.yml exists, no mdx counterpart
# after: create docs/set_settings.mdx.yml with the equivalent spec

// For each *.asciidoc.yml under the test root, assert a sibling *.mdx.yml exists:
// Files.exists(asciidocPath.resolveSibling(name.replace(".asciidoc.yml",".mdx.yml")))

When it happens

Trigger: Running the doc/REST test build in a repo that has migrated some docs from asciidoc to mdx. A new `*.asciidoc.yml` file was added (or renamed) without creating the matching `*.mdx.yml`, or the mdx file was deleted while the asciidoc one remains.

Common situations: Mid-migration branch where some pages have been ported to mdx and others have not; a contributor following the old (asciidoc) pattern adds a new spec without knowing the mdx mirror is required; case-sensitivity differences between the two filenames on a case-sensitive filesystem.

Related errors

• Yaml rest specs ({asciidocFile} and {mdxFile}) are not equal
• Yaml rest specs ({asciidocFile} and {mdxFile}) are not equal
• Unexpected unconverted snippets: {foundButNotListed}
• {name}: Snippet missing a language. This is required by Elas
• {name}: No need for NOTCONSOLE if snippet doesn't contain `c

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