microsoft/semantic-kernel · error · FunctionExecutionException

Either `openapi_document_path` or `openapi_parsed_spec` must

Error message

Either `openapi_document_path` or `openapi_parsed_spec` must be provided.

What it means

`create_functions_from_openapi` requires at least one input: either a file path (`openapi_document_path`) or an already-parsed spec dict (`openapi_parsed_spec`). If both are `None`, it raises `FunctionExecutionException`. The plugin cannot synthesize a REST surface from nothing.

Source

Thrown at python/semantic_kernel/connectors/openapi_plugin/openapi_manager.py:54

    execution_settings: "OpenAPIFunctionExecutionParameters | None" = None,
) -> list[KernelFunctionFromMethod]:
    """Creates the functions from OpenAPI document.

    Args:
        plugin_name: The name of the plugin
        openapi_document_path: The OpenAPI document path, it must be a file path to the spec (optional)
        openapi_parsed_spec: The parsed OpenAPI spec (optional)
        execution_settings: The execution settings

    Returns:
        list[KernelFunctionFromMethod]: the operations as functions
    """
    parsed_doc: dict[str, Any] | Any = None
    if openapi_parsed_spec is not None:
        parsed_doc = openapi_parsed_spec
    else:
        if openapi_document_path is None:
            raise FunctionExecutionException(
                "Either `openapi_document_path` or `openapi_parsed_spec` must be provided."
            )

        # Parse the document from the given path
        parser = OpenApiParser()
        parsed_doc = parser.parse(
            openapi_document_path,
            enable_file_ref_resolution=(execution_settings.enable_file_ref_resolution if execution_settings else False),
            enable_http_ref_resolution=(execution_settings.enable_http_ref_resolution if execution_settings else False),
        )
        if parsed_doc is None:
            raise FunctionExecutionException(f"Error parsing OpenAPI document: {openapi_document_path}")

    parser = OpenApiParser()
    operations = parser.create_rest_api_operations(parsed_doc, execution_settings=execution_settings)

    global_security_requirements = parsed_doc.get("security", [])

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Pass `openapi_document_path="/path/to/openapi.yaml"` with a real file path.
2. Or pass `openapi_parsed_spec=<dict>` containing the parsed document.
3. In your wrapper, assert the spec source is not None before calling the kernel API.
4. Log the resolved path/spec at startup so a misconfigured env var is obvious.

Example fix

# before
kernel.add_openapi_plugin(plugin_name="pets")  # raises 1484

# after
kernel.add_openapi_plugin(plugin_name="pets", openapi_document_path="/specs/pets.yaml")

def resolve_spec_source(path=None, parsed=None):
    if parsed is not None:
        return parsed, None
    if path is None:
        raise ValueError("Must provide openapi_document_path or openapi_parsed_spec")
    return None, path

parsed, path = resolve_spec_source(cfg.get("path"), cfg.get("spec"))
kwargs = {"openapi_parsed_spec": parsed} if parsed else {"openapi_document_path": path}
kernel.add_openapi_plugin(plugin_name="x", **kwargs)

def has_spec_source(path=None, parsed=None) -> bool:
    return path is not None or parsed is not None

from semantic_kernel.exceptions import FunctionExecutionException

try:
    kernel.add_openapi_plugin(plugin_name="x", openapi_document_path=path)
except FunctionExecutionException as e:
    if "must be provided" in str(e):
        raise ConfigError("OpenAPI spec source not configured") from e
    raise

When it happens

Trigger: Calling `kernel.add_openapi_plugin(plugin_name="x")` or `create_functions_from_openapi(plugin_name="x")` without supplying either `openapi_document_path` or `openapi_parsed_spec`. Also when a path variable read from config resolves to `None`.

Common situations: Forgetting to pass the spec argument; an env var / config key for the spec path being unset; refactoring a wrapper that previously defaulted the path; CI running with a missing mounted spec file passed as `None`.

Related errors

• Invalid server_url_override: {self.server_url_override}
• Failed to create AstraDB settings.
• Dimensionality of {self._embedding_dim} exceeds the maximum
• Failed to create Azure Cognitive Search settings.
• Error: missing Azure Cognitive Search client endpoint.

AI-assisted analysis of microsoft/semantic-kernel@c028a0c7dc (2026-08-13). Data as JSON: /api/errors/bc1a4f62f5f0050c. Report an issue: GitHub.