GitbookIO/gitbook · error · OpenAPIParseError

invalid

invalid

Error message

Invalid OpenAPI document

What it means

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.

Solutions

1. Read error.cause — the validation errors list every violated schema constraint with JSON pointers
2. Run the document through a validator (Redocly lint, swagger-cli validate) locally and fix reported issues
3. Confirm the URL actually returns the spec (not an HTML login/error page) by curl-ing it
4. Ensure openapi: 3.x.x (string) and required info/paths blocks exist exactly per spec

Example fix

# before
openapi: '3.0'
info: {}
path: {}

# after
openapi: 3.0.3
info:
  title: My API
  version: 1.0.0
paths: {}

// Lint before rendering
// npx @redocly/cli lint spec.yaml  → fix all errors first

function isInvalidDocumentError(e: unknown): e is OpenAPIParseError {
    return e instanceof OpenAPIParseError && e.code === 'invalid';
}

try {
    const result = await parseOpenAPI({ value: text, rootURL: url });
} catch (e) {
    if (isInvalidDocumentError(e)) {
        return renderInvalidSpecNotice(url, e.cause);
    }
    throw e;
}

When it happens

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

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

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• v2-conversion
• Expected schema of object to be provided
• Failed to fetch OpenAPI file
• Invalid hex color provided
• Unsupported schema type

AI-assisted analysis of GitbookIO/gitbook@db67585ee2 (2026-08-28). Data as JSON: /api/errors/dcbd199576366e79. Report an issue: GitHub.

Appendix: source

Thrown at packages/openapi-parser/src/v3.ts:16

import { validate } from '@scalar/openapi-parser';

import { OpenAPIParseError } from './error';
import { createFileSystem } from './filesystem';
import type { ParseOpenAPIInput, ParseOpenAPIResult } from './parse';

/**
 * Parse a raw string into an OpenAPI document.
 * It will also convert Swagger 2.0 to OpenAPI 3.0.
 * It can throw an `OpenAPIFetchError` if the document is invalid.
 */
export async function parseOpenAPIV3(input: ParseOpenAPIInput): Promise<ParseOpenAPIResult> {
    const { value, rootURL, options = {} } = input;

    const result = await validate(value).catch((error) => {
        throw new OpenAPIParseError('Invalid OpenAPI document', {
            code: 'invalid',
            rootURL,
            cause: error,
        });
    });

    // If there is no version, we consider it invalid instantely.
    if (!result.version) {
        throw new OpenAPIParseError(
            'Can’t find supported Swagger/OpenAPI version in the provided document, version must be a string.',
            {
                code: 'invalid',
                rootURL,
                errors: result.errors,
            }
        );
    }

View on GitHub (pinned to db67585ee2)