{"record":{"id":"dcbd199576366e79","repo":"GitbookIO/gitbook","slug":"invalid","errorCode":"invalid","errorMessage":"Invalid OpenAPI document","messagePattern":"Invalid OpenAPI document","errorType":"validation","errorClass":"OpenAPIParseError","httpStatus":null,"severity":"error","filePath":"packages/openapi-parser/src/v3.ts","lineNumber":16,"sourceCode":"import { validate } from '@scalar/openapi-parser';\n\nimport { OpenAPIParseError } from './error';\nimport { createFileSystem } from './filesystem';\nimport type { ParseOpenAPIInput, ParseOpenAPIResult } from './parse';\n\n/**\n * Parse a raw string into an OpenAPI document.\n * It will also convert Swagger 2.0 to OpenAPI 3.0.\n * It can throw an `OpenAPIFetchError` if the document is invalid.\n */\nexport async function parseOpenAPIV3(input: ParseOpenAPIInput): Promise<ParseOpenAPIResult> {\n    const { value, rootURL, options = {} } = input;\n\n    const result = await validate(value).catch((error) => {\n        throw new OpenAPIParseError('Invalid OpenAPI document', {\n            code: 'invalid',\n            rootURL,\n            cause: error,\n        });\n    });\n\n    // If there is no version, we consider it invalid instantely.\n    if (!result.version) {\n        throw new OpenAPIParseError(\n            'Can’t find supported Swagger/OpenAPI version in the provided document, version must be a string.',\n            {\n                code: 'invalid',\n                rootURL,\n                errors: result.errors,\n            }\n        );\n    }\n","sourceCodeStart":1,"sourceCodeEnd":34,"githubUrl":"https://github.com/GitbookIO/gitbook/blob/db67585ee243d063c459a855988f21612cea9c95/packages/openapi-parser/src/v3.ts#L1-L34","documentation":"parseOpenAPIV3 runs the document through schema validation; if validate() rejects, it throws OpenAPIParseError('Invalid OpenAPI document', code: 'invalid') with the underlying validation error as cause and rootURL for reporting. It fires before any parsing, meaning the document doesn't conform to the OpenAPI 3.x schema at all.","triggerScenarios":"Passing a YAML/JSON document that claims to be OpenAPI 3.x but violates the spec — missing required fields (info, paths, openapi version string), wrong value types (paths not an object), broken $refs during resolution, or a random JSON file fed to the parser.","commonSituations":"Typos in top-level keys (path instead of paths), missing info/version, YAML indentation errors that silently change structure, specs exported with non-string openapi field, or pointing the parser at an HTML error page instead of the spec file.","solutions":["Read error.cause — the validation errors list every violated schema constraint with JSON pointers","Run the document through a validator (Redocly lint, swagger-cli validate) locally and fix reported issues","Confirm the URL actually returns the spec (not an HTML login/error page) by curl-ing it","Ensure openapi: 3.x.x (string) and required info/paths blocks exist exactly per spec"],"exampleFix":"# before\nopenapi: '3.0'\ninfo: {}\npath: {}\n\n# after\nopenapi: 3.0.3\ninfo:\n  title: My API\n  version: 1.0.0\npaths: {}","handlingStrategy":"try-catch","validationCode":"// Lint before rendering\n// npx @redocly/cli lint spec.yaml  → fix all errors first","typeGuard":"function isInvalidDocumentError(e: unknown): e is OpenAPIParseError {\n    return e instanceof OpenAPIParseError && e.code === 'invalid';\n}","tryCatchPattern":"try {\n    const result = await parseOpenAPI({ value: text, rootURL: url });\n} catch (e) {\n    if (isInvalidDocumentError(e)) {\n        return renderInvalidSpecNotice(url, e.cause);\n    }\n    throw e;\n}","preventionTips":["Run schema validation in CI on every spec change","curl the spec URL to confirm it returns YAML/JSON, not an HTML page","Read error.cause — it carries per-field validation errors with JSON pointers"],"tags":["openapi","validation","schema","openapi-parser"],"backgroundTag":"schema-validation-failed","analyzedSha":"db67585ee243d063c459a855988f21612cea9c95","analyzedAt":"2026-08-28T17:49:47.831Z","schemaVersion":2},"datasetVersion":"2026-08-28T21:17:43.275Z"}