{"record":{"id":"a829163fbb606a93","repo":"PrefectHQ/fastmcp","slug":"invalid-openapi-specification-e","errorCode":null,"errorMessage":"Invalid OpenAPI specification: {e}","messagePattern":"Invalid OpenAPI specification: (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"fastmcp_slim/fastmcp/server/providers/openapi/provider.py","lineNumber":149,"sourceCode":"        self._used_names: dict[str, Counter[str]] = {\n            \"tool\": Counter(),\n            \"resource\": Counter(),\n            \"resource_template\": Counter(),\n            \"prompt\": Counter(),\n        }\n\n        # Pre-created component storage\n        self._tools: dict[str, OpenAPITool] = {}\n        self._resources: dict[str, OpenAPIResource] = {}\n        self._templates: dict[str, OpenAPIResourceTemplate] = {}\n\n        # Create openapi-core Spec and RequestDirector\n        try:\n            self._spec = SchemaPath.from_dict(cast(Any, openapi_spec))\n            self._director = RequestDirector(self._spec)\n        except Exception as e:\n            logger.exception(\"Failed to initialize RequestDirector\")\n            raise ValueError(f\"Invalid OpenAPI specification: {e}\") from e\n\n        http_routes = parse_openapi_to_http_routes(openapi_spec)\n\n        # Process routes\n        route_maps = (route_maps or []) + DEFAULT_ROUTE_MAPPINGS\n        for route in http_routes:\n            route_map = _determine_route_type(route, route_maps)\n            route_type = route_map.mcp_type\n\n            if route_map_fn is not None:\n                try:\n                    result = route_map_fn(route, route_type)\n                    if result is not None:\n                        route_type = result\n                        logger.debug(\n                            f\"Route {route.method} {route.path} mapping customized: \"\n                            f\"type={route_type.name}\"\n                        )","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/PrefectHQ/fastmcp/blob/1f021142978e0861cd910c8df4e8074bc7cf3978/fastmcp_slim/fastmcp/server/providers/openapi/provider.py#L131-L167","documentation":"OpenAPIProvider.__init__ builds an openapi-core SchemaPath spec and RequestDirector from the supplied spec dict; if that library rejects the document, the exception is logged and re-raised as ValueError('Invalid OpenAPI specification: ...').","triggerScenarios":"Passing a dict to OpenAPIProvider/FastMCPProvider that is not a valid OpenAPI document (openapi-core validation fails): wrong version field, missing paths, malformed schema objects.","commonSituations":"Passing a Swagger 2.0 doc instead of OpenAPI 3.x, YAML loaded into the wrong structure, truncated JSON, hand-edited specs with schema typos.","solutions":["Validate the spec with a linter (e.g. openapi-spec-validator or Swagger Editor)","Ensure spec['openapi'] is 3.x and 'paths' exists","Load the file correctly (yaml.safe_load / json.load) and pass the parsed dict","Read the chained message to find the offending schema path"],"exampleFix":"// before\nspec = {'swagger': '2.0', 'paths': {}}\nprovider = FastMCPProvider(spec)\n// after\nspec = {'openapi': '3.1.0', 'info': {'title': 'api', 'version': '1.0'}, 'paths': {...}}\nprovider = FastMCPProvider(spec)","handlingStrategy":"validation","validationCode":"from openapi_spec_validator import validate\ndef assert_valid_spec(spec: dict) -> None:\n    validate(spec)\nassert isinstance(spec, dict) and 'paths' in spec","typeGuard":"def is_valid_spec(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('paths'), dict)\n    )","tryCatchPattern":"try:\n    provider = FastMCPProvider(spec)\nexcept ValueError as e:\n    if str(e).startswith('Invalid OpenAPI specification'):\n        log.error('spec rejected: %s', e.__cause__)\n        raise\n    raise","preventionTips":["Run openapi-spec-validator on the document before loading","Convert Swagger 2.0 specs to OpenAPI 3.x first","Validate specs in CI to catch schema regressions"],"tags":["openapi","validation","configuration"],"backgroundTag":"invalid-openapi-spec","analyzedSha":"1f021142978e0861cd910c8df4e8074bc7cf3978","analyzedAt":"2026-08-29T14:31:16.082Z","schemaVersion":2},"datasetVersion":"2026-08-29T17:17:51.833Z"}