{"record":{"id":"25b885f459305667","repo":"OpenAPITools/openapi-generator","slug":"no-valid-specifications-found-to-merge","errorCode":null,"errorMessage":"No valid specifications found to merge","messagePattern":"No valid specifications found to merge","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"modules/openapi-generator/src/main/java/org/openapitools/codegen/config/MergedSpecBuilder.java","lineNumber":288,"sourceCode":"                            new OpenAPIResolver.Settings().addParametersToEachOperation(false))\n                            .resolve();\n                }\n                if (specs.isEmpty() && absolutePath.toLowerCase(Locale.ROOT).endsWith(\".json\")) {\n                    isJson = true;\n                }\n                if (openapiVersion == null) {\n                    openapiVersion = result.getOpenapi();\n                }\n                allServers.addAll(ObjectUtils.defaultIfNull(result.getServers(), Collections.emptyList()));\n                specs.add(result);\n                parsedPaths.add(absolutePath);\n            } catch (Exception e) {\n                LOGGER.error(\"Failed to read file: {}. It would be ignored\", absolutePath);\n            }\n        }\n\n        if (specs.isEmpty()) {\n            throw new RuntimeException(\"No valid specifications found to merge\");\n        }\n\n        return new ParsedSpecFiles(specs, parsedPaths, isJson, openapiVersion, allServers);\n    }\n\n    // -------------------------------------------------------------------------\n    // REF mode — original $ref-based shallow merge (identical to master)\n    // -------------------------------------------------------------------------\n\n    private String buildRefMergedSpec(ParsedSpecFiles parsed, String outputDir) {\n        // Normalize to an absolute path: relativize() requires both paths to be of the same type\n        // (both absolute or both relative). The spec paths are always absolute, so a relative\n        // outputDir (e.g. a plain directory name passed from the CLI/Gradle) would otherwise throw.\n        Path outDirPath = Paths.get(outputDir).toAbsolutePath().normalize();\n\n        List<SpecWithPaths> allPaths = new ArrayList<>();\n        for (int i = 0; i < parsed.specs.size(); i++) {\n            io.swagger.v3.oas.models.Paths specPaths = parsed.specs.get(i).getPaths();","sourceCodeStart":270,"sourceCodeEnd":306,"githubUrl":"https://github.com/OpenAPITools/openapi-generator/blob/fcec517be3cf5b7964296bcba25fbc97541484e7/modules/openapi-generator/src/main/java/org/openapitools/codegen/config/MergedSpecBuilder.java#L270-L306","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Scan the log for every 'Failed to read file: <path>' line — those are the real failures; fix each file (syntax, encoding, permissions).","Validate each file independently (swagger-cli validate / spectral) before merging.","Ensure files end in valid YAML/JSON and carry an openapi field.","Re-run after fixing to confirm at least one file parses."],"exampleFix":"# before: specs contain unresolved pipeline placeholders\ninfo:\n  version: ${VERSION}\n# after\ninfo:\n  version: 1.0.0","handlingStrategy":"validation","validationCode":"// Pre-parse every candidate so a bad file is reported by name, not swallowed\nOpenAPIV3Parser parser = new OpenAPIV3Parser();\nfor (String path : candidates) {\n    if (parser.read(path) == null) throw new IllegalArgumentException(\"Unparseable spec: \" + path);\n}","typeGuard":null,"tryCatchPattern":"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.","preventionTips":["Validate each spec individually before merging (spectral/swagger-cli).","Keep template placeholders out of committed spec files.","Watch file encoding: strip BOM artifacts."],"tags":["openapi","spec-merge","parse-error","yaml","json"],"backgroundTag":"spec-parse-failed","analyzedSha":"fcec517be3cf5b7964296bcba25fbc97541484e7","analyzedAt":"2026-08-22T11:13:11.613Z","schemaVersion":2},"datasetVersion":"2026-08-22T14:17:55.899Z"}