{"record":{"id":"6a8041eeac193822","repo":"microsoft/semantic-kernel","slug":"error-parsing-openapi-document-openapi-document","errorCode":null,"errorMessage":"Error parsing OpenAPI document: {openapi_document_path}","messagePattern":"Error parsing OpenAPI document: (.+?)","errorType":"exception","errorClass":"FunctionExecutionException","httpStatus":null,"severity":"error","filePath":"python/semantic_kernel/connectors/openapi_plugin/openapi_manager.py","lineNumber":66,"sourceCode":"    \"\"\"\n    parsed_doc: dict[str, Any] | Any = None\n    if openapi_parsed_spec is not None:\n        parsed_doc = openapi_parsed_spec\n    else:\n        if openapi_document_path is None:\n            raise FunctionExecutionException(\n                \"Either `openapi_document_path` or `openapi_parsed_spec` must be provided.\"\n            )\n\n        # Parse the document from the given path\n        parser = OpenApiParser()\n        parsed_doc = parser.parse(\n            openapi_document_path,\n            enable_file_ref_resolution=(execution_settings.enable_file_ref_resolution if execution_settings else False),\n            enable_http_ref_resolution=(execution_settings.enable_http_ref_resolution if execution_settings else False),\n        )\n        if parsed_doc is None:\n            raise FunctionExecutionException(f\"Error parsing OpenAPI document: {openapi_document_path}\")\n\n    parser = OpenApiParser()\n    operations = parser.create_rest_api_operations(parsed_doc, execution_settings=execution_settings)\n\n    global_security_requirements = parsed_doc.get(\"security\", [])\n\n    auth_callback = None\n    if execution_settings and execution_settings.auth_callback:\n        auth_callback = execution_settings.auth_callback\n\n    openapi_runner = OpenApiRunner(\n        parsed_openapi_document=parsed_doc,\n        auth_callback=auth_callback,\n        http_client=execution_settings.http_client if execution_settings else None,\n        enable_dynamic_payload=execution_settings.enable_dynamic_payload if execution_settings else True,\n        enable_payload_namespacing=execution_settings.enable_payload_namespacing if execution_settings else False,\n        server_url_validation_options=ServerUrlValidationOptions(\n            allowed_base_urls=execution_settings.server_url_validation_allowed_base_urls,","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/microsoft/semantic-kernel/blob/c028a0c7dc4f0814cdcbaba9d998f187a41197bf/python/semantic_kernel/connectors/openapi_plugin/openapi_manager.py#L48-L84","documentation":"`OpenApiParser.parse()` returned `None`, meaning the OpenAPI document at `openapi_document_path` could not be parsed into a usable spec. The manager then refuses to continue and raises `FunctionExecutionException` so an empty/broken plugin is never registered silently.","triggerScenarios":"The file exists and is readable but its contents are not a valid OpenAPI document (malformed YAML/JSON, wrong structure, `$ref` resolution failures, or an empty file), causing `parse()` to yield `None`.","commonSituations":"Pointing at the wrong file (e.g. a README or a JSON error response); a half-downloaded spec; a spec with unresolved `$ref`s when ref resolution is disabled; a corrupted file in CI artifact; YAML indentation errors.","solutions":["Open the file and validate it is a well-formed OpenAPI document (try `swagger-cli validate` / `openapi-spec-validator`).","Confirm the path points at the intended spec and the file is non-empty.","If `$ref` resolution fails, enable `enable_file_ref_resolution`/`enable_http_ref_resolution` in the execution settings or bundle the spec first.","Check the parser's own logs for the underlying parse error before retrying."],"exampleFix":"# before\nkernel.add_openapi_plugin(plugin_name=\"x\", openapi_document_path=\"/specs/broken.yaml\")  # raises 1485\n\n# after\n# validate first\nimport yaml, pathlib\nspec = yaml.safe_load(pathlib.Path(\"/specs/x.yaml\").read_text())\nassert spec and \"paths\" in spec\nkernel.add_openapi_plugin(plugin_name=\"x\", openapi_parsed_spec=spec)","handlingStrategy":"validation","validationCode":"import yaml, json, pathlib\n\ndef load_and_validate_spec(path: str) -> dict:\n    text = pathlib.Path(path).read_text()\n    spec = yaml.safe_load(text) if path.endswith((\".yaml\", \".yml\")) else json.loads(text)\n    if not isinstance(spec, dict) or \"paths\" not in spec:\n        raise ValueError(f\"{path} did not parse into a valid OpenAPI document\")\n    return spec\n\nspec = load_and_validate_spec(path)\nkernel.add_openapi_plugin(plugin_name=\"x\", openapi_parsed_spec=spec)","typeGuard":"def looks_like_openapi(spec) -> bool:\n    return isinstance(spec, dict) and (\"openapi\" in spec or \"swagger\" in spec) and \"paths\" in spec","tryCatchPattern":"from semantic_kernel.exceptions import FunctionExecutionException\n\ntry:\n    kernel.add_openapi_plugin(plugin_name=\"x\", openapi_document_path=path)\nexcept FunctionExecutionException as e:\n    if \"Error parsing OpenAPI document\" in str(e):\n        # validate file with an external linter, fix, then retry\n        raise ConfigError(f\"Unparseable spec at {path}\") from e\n    raise","preventionTips":["Lint specs in CI with openapi-spec-validator / spectral.","Assert non-empty file before loading.","Bundle multi-file specs before passing to the kernel.","Log parser internals at DEBUG to see why parse() returned None."],"tags":["openapi-plugin","parsing","semantic-kernel"],"backgroundTag":null,"analyzedSha":"c028a0c7dc4f0814cdcbaba9d998f187a41197bf","analyzedAt":"2026-08-13T13:48:05.040Z","schemaVersion":2},"datasetVersion":"2026-08-13T14:17:21.547Z"}