GitbookIO/gitbook · error · OpenAPIParseError

v2-conversion

v2-conversion

Error message

Failed to convert Swagger 2.0 to OpenAPI 3.1.1

What it means

The openapi-parser first tries to upgrade Swagger 2.0 documents to OpenAPI 3.1.1; when the internal upgrade() conversion throws, it wraps the failure as OpenAPIParseError with code 'v2-conversion'. It means the document was recognized as v2 but its structure could not be transformed — usually schema constructs the converter can't map.

Source

Thrown at packages/openapi-parser/src/v2.ts:27

 */
export async function convertOpenAPIV2ToOpenAPIV3(
    input: ParseOpenAPIInput
): Promise<ParseOpenAPIResult> {
    const result = upgradeFromInput(input);
    return parseOpenAPIV3({ ...input, rootURL: input.rootURL, value: result.specification });
}

/**
 * Upgrade a Swagger 2.0 schema to an OpenAPI 3.0 schema.
 * This function will throw an error if the conversion fails.
 */
function upgradeFromInput(input: ParseOpenAPIInput) {
    const { value, rootURL } = input;
    try {
        return upgrade(value);
    } catch (error) {
        if (error instanceof Error) {
            throw new OpenAPIParseError('Failed to convert Swagger 2.0 to OpenAPI 3.1.1', {
                code: 'v2-conversion',
                rootURL,
                cause: error,
            });
        }

        throw error;
    }
}

View on GitHub (pinned to db67585ee2)

Solutions

1. Inspect error.cause — the underlying upgrade error names the exact failing construct
2. Validate/fix the spec with a Swagger 2.0 linter (swagger-cli validate) before passing it in
3. If possible, convert the document manually with swagger2openapi (with --warnOnly to see all issues), fix reported nodes, then serve the converted 3.x spec
4. As a stopgap, isolate and remove/simplify the offending definition and retry parsing

Example fix

# before
# feed legacy swagger.yaml directly

# after
npx swagger2openapi legacy-swagger.yaml -o openapi3.json
# fix any reported conversion warnings, then:
# point the GitBook OpenAPI block at openapi3.json

// Pre-convert with warnings surfaced before rendering
import { convertOpenAPIV2ToOpenAPIV3 } from '@gitbook/openapi-parser';
await convertOpenAPIV2ToOpenAPIV3({ value, rootURL }); // throws early with cause

function isV2ConversionError(e: unknown): e is OpenAPIParseError {
    return e instanceof OpenAPIParseError && e.code === 'v2-conversion';
}

try {
    const result = await parseOpenAPI({ value: text, rootURL: url });
} catch (e) {
    if (isV2ConversionError(e)) {
        console.error('Cause:', e.cause);
        return renderSpecConversionNotice(url);
    }
    throw e;
}

When it happens

Trigger: Feeding a Swagger 2.0 spec containing constructs the upgrader chokes on — unusual $ref placements, non-standard type coercion cases, malformed definitions, or extension fields (x-*) with unexpected value shapes — so the upgrade pass throws an Error.

Common situations: Legacy enterprise Swagger 2.0 specs with hand-edited definitions; specs generated by old tooling (Swagger Editor 2.x, SoapUI) with quirks; docs that are actually invalid Swagger 2.0 but superficially parseable.

Related errors

• invalid
• Failed to fetch OpenAPI file

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