{"record":{"id":"b5892d7e84ba5b83","repo":"alibaba/nacos","slug":"file-format-invalid-not-a-valid-openapi-or-swagge","errorCode":null,"errorMessage":"File format invalid: not a valid OpenAPI or Swagger document","messagePattern":"File format invalid: not a valid OpenAPI or Swagger document","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"console-ui-next/src/utils/openapi/parseOpenApi.ts","lineNumber":78,"sourceCode":"      parsed = YAML.load(content);\n    } catch {\n      throw new Error('Invalid JSON/YAML format');\n    }\n  }\n\n  parsed = resolveRefs(parsed, parsed);\n\n  // Swagger 2.x -> OpenAPI 3.x\n  if (parsed.swagger) {\n    const converted = await swagger2openapi.convertObj(parsed, {});\n    return converted.openapi;\n  }\n\n  if (parsed.openapi) {\n    return parsed;\n  }\n\n  throw new Error('File format invalid: not a valid OpenAPI or Swagger document');\n}\n","sourceCodeStart":60,"sourceCodeEnd":80,"githubUrl":"https://github.com/alibaba/nacos/blob/9b989acdf181d00898f2e8839257bb2b2a3cefe3/console-ui-next/src/utils/openapi/parseOpenApi.ts#L60-L80","documentation":"Thrown by parseOpenAPI() after the content was successfully parsed as JSON or YAML but the resulting document has neither a `swagger` field (Swagger 2.x marker) nor an `openapi` field (OpenAPI 3.x marker). The parser cannot determine the spec version, so it rejects the document as not a valid OpenAPI/Swagger file.","triggerScenarios":"Uploading a valid JSON/YAML document that is a different schema entirely (e.g. an AsyncAPI doc, a JSON Schema, a Postman collection, a package.json) — it parses fine but lacks the version discriminator field. Also triggered by an OpenAPI doc where the top-level version field was accidentally removed or renamed.","commonSituations":"User uploads an AsyncAPI spec (has 'asyncapi' not 'openapi'). User uploads a generic JSON config. OpenAPI doc hand-edited and the 'openapi: 3.0.0' line deleted. Swagger doc with 'swaggerVersion' instead of 'swagger'.","solutions":["Verify the document has an 'openapi' field (e.g. '3.0.3') for OpenAPI 3.x or a 'swagger' field (e.g. '2.0') for Swagger 2.x at the top level.","If the file is AsyncAPI or another spec, convert it to OpenAPI first.","Open the file in a spec editor (Swagger Editor) to confirm it is recognized.","Catch the error and tell the user which field is missing."],"exampleFix":"// before\nconst doc = await parseOpenAPI(content);\n\n// after\nconst doc = await parseOpenAPI(content);\n// (parseOpenAPI already enforces this; pre-check for a friendlier message:)\nconst preview = JSON.parse(content);\nif (!preview.openapi && !preview.swagger) {\n  throw new Error('Missing openapi or swagger field — not a valid OpenAPI/Swagger document.');\n}","handlingStrategy":"validation","validationCode":"function looksLikeOpenApi(content: string): boolean {\n  let parsed: any;\n  try { parsed = JSON.parse(content); } catch { try { parsed = YAML.load(content); } catch { return false; } }\n  return !!(parsed && (parsed.openapi || parsed.swagger));\n}","typeGuard":"function isOpenApiDocument(doc: any): boolean {\n  return !!doc && (typeof doc.openapi === 'string' || typeof doc.swagger === 'string');\n}","tryCatchPattern":"try {\n  const doc = await parseOpenAPI(content);\n} catch (e) {\n  if (e.message.startsWith('File format invalid')) {\n    setError('This document has no openapi/swagger version field — not a valid spec.');\n    return;\n  }\n  throw e;\n}","preventionTips":["Check for a top-level openapi or swagger field before importing.","Reject AsyncAPI/Postman/JSON-Schema files at the upload boundary.","Open specs in a validator (Swagger Editor) before upload."],"tags":["openapi","swagger","typescript","validation","spec"],"backgroundTag":null,"analyzedSha":"9b989acdf181d00898f2e8839257bb2b2a3cefe3","analyzedAt":"2026-08-14T07:17:31.569Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}