alibaba/nacos · error · Error

File format invalid: not a valid OpenAPI or Swagger document

Error message

File format invalid: not a valid OpenAPI or Swagger document

What it means

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.

Source

Thrown at console-ui-next/src/utils/openapi/parseOpenApi.ts:78

      parsed = YAML.load(content);
    } catch {
      throw new Error('Invalid JSON/YAML format');
    }
  }

  parsed = resolveRefs(parsed, parsed);

  // Swagger 2.x -> OpenAPI 3.x
  if (parsed.swagger) {
    const converted = await swagger2openapi.convertObj(parsed, {});
    return converted.openapi;
  }

  if (parsed.openapi) {
    return parsed;
  }

  throw new Error('File format invalid: not a valid OpenAPI or Swagger document');
}

View on GitHub (pinned to 9b989acdf1)

Solutions

  1. 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.
  2. If the file is AsyncAPI or another spec, convert it to OpenAPI first.
  3. Open the file in a spec editor (Swagger Editor) to confirm it is recognized.
  4. Catch the error and tell the user which field is missing.

Example fix

// before
const doc = await parseOpenAPI(content);

// after
const doc = await parseOpenAPI(content);
// (parseOpenAPI already enforces this; pre-check for a friendlier message:)
const preview = JSON.parse(content);
if (!preview.openapi && !preview.swagger) {
  throw new Error('Missing openapi or swagger field — not a valid OpenAPI/Swagger document.');
}
Defensive patterns

Strategy: validation

Validate before calling

function looksLikeOpenApi(content: string): boolean {
  let parsed: any;
  try { parsed = JSON.parse(content); } catch { try { parsed = YAML.load(content); } catch { return false; } }
  return !!(parsed && (parsed.openapi || parsed.swagger));
}

Type guard

function isOpenApiDocument(doc: any): boolean {
  return !!doc && (typeof doc.openapi === 'string' || typeof doc.swagger === 'string');
}

Try / catch

try {
  const doc = await parseOpenAPI(content);
} catch (e) {
  if (e.message.startsWith('File format invalid')) {
    setError('This document has no openapi/swagger version field — not a valid spec.');
    return;
  }
  throw e;
}

Prevention

When it happens

Trigger: 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.

Common situations: 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'.

Related errors

AI-assisted analysis of alibaba/nacos@9b989acdf1 (2026-08-14). Data as JSON: /api/errors/b5892d7e84ba5b83. Report an issue: GitHub.