OpenAPITools/openapi-generator · error · RuntimeException

Spec directory doesn't contain any specification

Error message

Spec directory doesn't contain any specification

What it means

In directory mode (inputSpecFiles null, inputSpecRootDirectory set), MergedSpecBuilder scans the spec root directory for spec files and throws this when the scan returns nothing. The directory exists but contains no files the builder recognizes as specifications. Note a previous run's merged output is deleted first (deleteMergedFileFromPreviousRun), so a directory that only held the merged file also lands here.

Source

Thrown at modules/openapi-generator/src/main/java/org/openapitools/codegen/config/MergedSpecBuilder.java:182

            return buildMergedSpecFromList();
        }
        return buildMergedSpecFromDirectory();
    }

    private String buildMergedSpecFromList() {
        if (inputSpecFiles.isEmpty()) {
            throw new RuntimeException("inputSpecFiles list is empty — nothing to merge");
        }
        deleteMergedFileFromPreviousRun();
        LOGGER.info("Merging {} explicit spec files into {}", inputSpecFiles.size(), outputDirectory);
        return buildMergedSpec(inputSpecFiles, outputDirectory);
    }

    private String buildMergedSpecFromDirectory() {
        deleteMergedFileFromPreviousRun();
        List<String> specRelatedPaths = getAllSpecFilesInDirectory();
        if (specRelatedPaths.isEmpty()) {
            throw new RuntimeException("Spec directory doesn't contain any specification");
        }
        LOGGER.info("In spec root directory {} found specs {}", inputSpecRootDirectory, specRelatedPaths);
        // Resolve relative paths to absolute so the shared build logic works uniformly
        List<String> absolutePaths = specRelatedPaths.stream()
                .map(rel -> Paths.get(inputSpecRootDirectory, rel).toAbsolutePath().toString())
                .collect(Collectors.toList());
        return buildMergedSpec(absolutePaths, inputSpecRootDirectory);
    }

    /**
     * Core merge logic shared by both directory mode and list mode.
     *
     * @param absoluteSpecPaths absolute paths to each spec file to parse, in merge order
     * @param outputDir         directory where the merged output file will be written
     */
    private String buildMergedSpec(List<String> absoluteSpecPaths, String outputDir) {
        // In DEEP mode we inline everything into a single self-contained file, so external
        // ($ref to another file) references must be resolved and pulled into components up front;

View on GitHub (pinned to fcec517be3)

Solutions

1. Verify inputSpecRootDirectory points at the folder actually containing the spec files (print the absolute path before running).
2. Check the directory contains files recognized as specs by getAllSpecFilesInDirectory — rename/move stray files or fix extensions.
3. If specs are nested, point at the correct level or switch to explicit list mode with inputSpecFiles.
4. Re-checkout submodules/artifact sources in CI before the merge step.

Example fix

# before
--input-spec-root-dir ./output   # only holds last run's merged.json
# after
--input-spec-root-dir ./src/openapi   # holds pet.yaml, store.yaml

Path root = Paths.get(inputSpecRootDirectory).toAbsolutePath();
if (!Files.isDirectory(root)) throw new IllegalArgumentException("not a directory: " + root);
long specCount;
try (Stream<Path> s = Files.walk(root)) {
    specCount = s.filter(p -> p.toString().endsWith(".yaml") || p.toString().endsWith(".yml") || p.toString().endsWith(".json")).count();
}
if (specCount == 0) throw new IllegalStateException("no spec files under " + root);

Catch RuntimeException with "doesn't contain any specification"; print the resolved absolute directory path in the error and stop.

When it happens

Trigger: Pointing inputSpecRootDirectory at an empty folder; a folder whose files don't match the expected spec file extensions/naming; running merge twice into the same directory where the first run's merged output was cleaned and sources live elsewhere; wrong/relative directory resolved from a different working directory.

Common situations: CI checkouts missing the specs submodule; path typos or case-sensitivity on Linux; specs living one level deeper than configured; re-running generation against an output directory instead of the source directory.

Related errors

• {name}
• inputSpecFiles list is empty — nothing to merge
• No valid specifications found to merge
• Failed to serialize merged spec
• Cannot merge specs where some declare an OpenAPI version and

AI-assisted analysis of OpenAPITools/openapi-generator@fcec517be3 (2026-08-22). Data as JSON: /api/errors/4a3f4a48dc5a7d56. Report an issue: GitHub.