{"record":{"id":"5c73f81730d0e4f2","repo":"kubesphere/kubesphere","slug":"failed-to-build-merge-specs-v","errorCode":null,"errorMessage":"failed to build merge specs: %v","messagePattern":"failed to build merge specs: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"kube/pkg/openapi/v2/services.go","lineNumber":86,"sourceCode":"func (s *OpenApiV2Services) RemoveApiService(apiServiceName string) {\n\ts.openApiAggregatorService.RemoveApiService(apiServiceName)\n\tdelete(s.openApiSpecCache, apiServiceName)\n}\n\nfunc (s *OpenApiV2Services) MergeSpecCache() (*spec.Swagger, error) {\n\tvar merged *spec.Swagger\n\tfor i := range s.openApiSpecCache {\n\t\tif cacheValue, ok := s.openApiSpecCache[i]; ok {\n\t\t\tcacheSpec := cacheValue.Load()\n\t\t\tif merged == nil {\n\t\t\t\tmerged = &spec.Swagger{}\n\t\t\t\t*merged = *cacheSpec\n\t\t\t\tmerged.Paths = nil\n\t\t\t\tmerged.Definitions = nil\n\t\t\t\tmerged.Parameters = nil\n\t\t\t}\n\t\t\tif err := merge.MergeSpecsIgnorePathConflictRenamingDefinitionsAndParameters(merged, cacheSpec); err != nil {\n\t\t\t\treturn nil, fmt.Errorf(\"failed to build merge specs: %v\", err)\n\t\t\t}\n\t\t}\n\t}\n\treturn merged, nil\n}\n\nfunc (s *OpenApiV2Services) RegisterOpenAPIVersionedService(servePath string, handler openapi.PathHandler) {\n\thandler.Handle(servePath, gziphandler.GzipHandler(http.HandlerFunc(\n\t\tfunc(w http.ResponseWriter, r *http.Request) {\n\n\t\t\tresult, err := s.MergeSpecCache()\n\t\t\tif err != nil {\n\t\t\t\tklog.Errorf(\"Error in OpenAPI handler: %s\", err)\n\t\t\t\t// only return a 503 if we have no older cache data to serve\n\t\t\t\tif result == nil {\n\t\t\t\t\tw.WriteHeader(http.StatusServiceUnavailable)\n\t\t\t\t\treturn\n\t\t\t\t}","sourceCodeStart":68,"sourceCodeEnd":104,"githubUrl":"https://github.com/kubesphere/kubesphere/blob/04a29b5c601470fa6bc2f2e92358dcb802a0d414/kube/pkg/openapi/v2/services.go#L68-L104","documentation":"v2.MergeSpecCache builds a single merged OpenAPI v2 spec from all cached APIService specs using MergeSpecsIgnorePathConflictRenamingDefinitionsAndParameters. This error wraps any failure of that merge (including the GVK extension shape errors 60-63) with a 'failed to build merge specs' prefix.","triggerScenarios":"During MergeSpecCache iteration over cached specs, merging a subsequent cached spec into the accumulated merged spec fails — typically because a cached spec has a malformed x-kubernetes-group-version-kind extension or otherwise incompatible spec content.","commonSituations":"One corrupted or hand-written cached spec poisons the whole merge; specs from differently-versioned generators conflict; empty/invalid cached documents left after failed downloads.","solutions":["Identify the inner (wrapped) error to find the offending cached spec and fix or delete that cache entry","Clear the spec cache so all specs are re-downloaded and re-merged","Fix the malformed extension in the offending spec (array of {group,kind,version} objects)","Validate each cached spec parses and has well-formed extensions before merging"],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":"// pre-validate cached specs before merging\nfor name, spec := range cache {\n    if !validGVKExtension(spec) {\n        invalidateCacheEntry(name)\n    }\n}","typeGuard":"func validGVKExtension(spec map[string]interface{}) bool {\n    ext, ok := spec[\"x-kubernetes-group-version-kind\"].([]interface{})\n    if !ok { return false }\n    for _, x := range ext {\n        if _, ok := x.(map[string]interface{}); !ok { return false }\n    }\n    return true\n}","tryCatchPattern":"merged, err := v2.MergeSpecCache(cache)\nif err != nil {\n    if strings.Contains(err.Error(), \"failed to build merge specs\") {\n        // identify and purge the offending cache entry, then rebuild\n        clearCache()\n        return v2.MergeSpecCache(reloadCache())\n    }\n    return err\n}","preventionTips":["Purge and rebuild the spec cache after unexplained merge failures","Validate every cached spec's extensions before merging","Keep spec generators consistent across all aggregated APIs"],"tags":["openapi","spec-merge","cache","kube-aggregator"],"backgroundTag":"openapi-spec-merge-failed","analyzedSha":"04a29b5c601470fa6bc2f2e92358dcb802a0d414","analyzedAt":"2026-09-03T18:33:15.017Z","contentChangedAt":"2026-09-03T18:33:15.017Z","schemaVersion":2},"datasetVersion":"2026-09-11T00:17:11.886Z"}