OpenAPITools/openapi-generator · error · RuntimeException

No valid specifications found to merge

Error message

No valid specifications found to merge

What it means

After iterating candidate spec files, MergedSpecBuilder collects successfully parsed OpenAPI documents; files that throw during parsing are logged as 'Failed to read file: ... It would be ignored' and skipped. If zero files parsed, this RuntimeException is thrown — inputs were found but every one was unreadable/unparseable, so there is nothing to merge. Distinguish it from error 34 (no candidates found at all) by the absence of the failed-file log lines.

Source

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

                            new OpenAPIResolver.Settings().addParametersToEachOperation(false))
                            .resolve();
                }
                if (specs.isEmpty() && absolutePath.toLowerCase(Locale.ROOT).endsWith(".json")) {
                    isJson = true;
                }
                if (openapiVersion == null) {
                    openapiVersion = result.getOpenapi();
                }
                allServers.addAll(ObjectUtils.defaultIfNull(result.getServers(), Collections.emptyList()));
                specs.add(result);
                parsedPaths.add(absolutePath);
            } catch (Exception e) {
                LOGGER.error("Failed to read file: {}. It would be ignored", absolutePath);
            }
        }

        if (specs.isEmpty()) {
            throw new RuntimeException("No valid specifications found to merge");
        }

        return new ParsedSpecFiles(specs, parsedPaths, isJson, openapiVersion, allServers);
    }

    // -------------------------------------------------------------------------
    // REF mode — original $ref-based shallow merge (identical to master)
    // -------------------------------------------------------------------------

    private String buildRefMergedSpec(ParsedSpecFiles parsed, String outputDir) {
        // Normalize to an absolute path: relativize() requires both paths to be of the same type
        // (both absolute or both relative). The spec paths are always absolute, so a relative
        // outputDir (e.g. a plain directory name passed from the CLI/Gradle) would otherwise throw.
        Path outDirPath = Paths.get(outputDir).toAbsolutePath().normalize();

        List<SpecWithPaths> allPaths = new ArrayList<>();
        for (int i = 0; i < parsed.specs.size(); i++) {
            io.swagger.v3.oas.models.Paths specPaths = parsed.specs.get(i).getPaths();

View on GitHub (pinned to fcec517be3)

Solutions

1. Scan the log for every 'Failed to read file: <path>' line — those are the real failures; fix each file (syntax, encoding, permissions).
2. Validate each file independently (swagger-cli validate / spectral) before merging.
3. Ensure files end in valid YAML/JSON and carry an openapi field.
4. Re-run after fixing to confirm at least one file parses.

Example fix

# before: specs contain unresolved pipeline placeholders
info:
  version: ${VERSION}
# after
info:
  version: 1.0.0

// Pre-parse every candidate so a bad file is reported by name, not swallowed
OpenAPIV3Parser parser = new OpenAPIV3Parser();
for (String path : candidates) {
    if (parser.read(path) == null) throw new IllegalArgumentException("Unparseable spec: " + path);
}

catch (RuntimeException e) when message contains "No valid specifications" — collect the per-file 'Failed to read file' log lines and present them as the actionable cause list.

When it happens

Trigger: All candidate files are invalid YAML/JSON or not OpenAPI documents; files are unreadable (permissions); YAML with duplicate keys or bad anchors that the parser rejects for every file in the set.

Common situations: Spec files containing template placeholders or BOM/encoding artifacts; JSON specs truncated by a failed pipeline step; permissions in containers; a whole directory of specs generated by a tool writing invalid output.

Related errors

• Unable to deserialize config file: {configFile}
• Could not process model '{name}'.Please make sure that your
• inputSpecFiles list is empty — nothing to merge
• Spec directory doesn't contain any specification
• Failed to serialize merged spec

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