{"record":{"id":"2b45dd56edff7672","repo":"PrefectHQ/fastmcp","slug":"invalid-openapi-schema-error-details","errorCode":null,"errorMessage":"Invalid OpenAPI schema: {error_details}","messagePattern":"Invalid OpenAPI schema: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/utilities/openapi/parser.py","lineNumber":107,"sourceCode":"                f\"Successfully parsed OpenAPI 3.1 schema version: {openapi_31.openapi}\"\n            )\n            parser = OpenAPIParser(\n                openapi_31,\n                Reference,\n                Schema,\n                Parameter,\n                RequestBody,\n                Response,\n                Operation,\n                PathItem,\n                openapi_version,\n            )\n            return parser.parse()\n    except ValidationError as e:\n        logger.error(f\"OpenAPI schema validation failed: {e}\")\n        error_details = e.errors()\n        logger.error(f\"Validation errors: {error_details}\")\n        raise ValueError(f\"Invalid OpenAPI schema: {error_details}\") from e\n\n\nclass OpenAPIParser(\n    Generic[\n        TOpenAPI,\n        TReference,\n        TSchema,\n        TParameter,\n        TRequestBody,\n        TResponse,\n        TOperation,\n        TPathItem,\n    ]\n):\n    \"\"\"Unified parser for OpenAPI schemas with generic type parameters to handle both 3.0 and 3.1.\"\"\"\n\n    def __init__(\n        self,","sourceCodeStart":89,"sourceCodeEnd":125,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/utilities/openapi/parser.py#L89-L125","documentation":"parse_openapi_to_http_routes validates the raw OpenAPI document against pydantic models for the spec version. If validation fails (spec doesn't match OpenAPI 3.0/3.1 required structure), it logs the pydantic errors and re-raises them wrapped as ValueError('Invalid OpenAPI schema: ...'). This means the document was readable but structurally invalid as an OpenAPI schema, not that the network or file access failed.","triggerScenarios":"Calling parse_openapi_to_http_routes(spec) (directly or via OpenAPIClient/FastMCP.from_openapi-style integration) with a dict/JSON that violates required OpenAPI fields — missing `openapi` version key, missing `info`, missing `paths`, or fields with wrong types (e.g. `paths: []` instead of an object).","commonSituations":"Hand-written or LLM-generated specs missing required fields; Swagger 2.0 documents passed where 3.x is required; tools exporting incomplete specs; API gateways returning an HTML error page or truncated JSON that got parsed as a spec; minor-version fields typed incorrectly after spec upgrade.","solutions":["Read the pydantic error list embedded in the message — each entry gives the failing field path (loc), message, and type; fix those fields first.","Validate the document with a standalone validator (e.g. `openapi-spec-validator`) before passing it, to get richer diagnostics.","Confirm the document is OpenAPI 3.0/3.1, not Swagger 2.0 — convert 2.0 specs first (e.g. swagger2openapi).","Re-export the spec from the source tool (FastAPI /postman/ gateway) ensuring a complete 3.x export, then diff against the failing one.","Check that what you passed is the parsed JSON spec object, not a wrapper like {'spec': {...}} or an HTTP response object."],"exampleFix":"// before\nwith open(\"spec.json\") as f:\n    routes = parse_openapi_to_http_routes(json.load(f))\n\n// after\nfrom openapi_spec_validator import validate_spec\nwith open(\"spec.json\") as f:\n    spec = json.load(f)\nvalidate_spec(spec)  # raises with detailed diagnostics first\nroutes = parse_openapi_to_http_routes(spec)","handlingStrategy":"validation","validationCode":"from openapi_spec_validator import validate_spec\n\ndef load_valid_spec(path: str) -> dict:\n    with open(path) as f:\n        spec = json.load(f)\n    validate_spec(spec)\n    return spec\n\nroutes = parse_openapi_to_http_routes(load_valid_spec(\"spec.json\"))","typeGuard":"def is_openapi3(spec: object) -> bool:\n    return (\n        isinstance(spec, dict)\n        and isinstance(spec.get(\"openapi\"), str)\n        and spec[\"openapi\"].startswith(\"3.\")\n        and isinstance(spec.get(\"info\"), dict)\n        and isinstance(spec.get(\"paths\"), dict)\n    )","tryCatchPattern":"try:\n    routes = parse_openapi_to_http_routes(spec)\nexcept ValueError as e:\n    logger.error(\"Spec rejected: %s\", e)\n    raise SystemExit(\"Fix the OpenAPI schema fields listed above\") from e","preventionTips":["Run openapi-spec-validator in CI on every exported spec.","Never hand-write specs; export from a framework (FastAPI, Fastify) that guarantees 3.x structure.","Convert Swagger 2.0 documents before use.","Log/inspect the pydantic 'loc' paths in the message to fix fields fastest."],"tags":["openapi","validation","schema"],"backgroundTag":"schema-validation-failed","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}