microsoft/semantic-kernel · error · PluginInitializationError

operationId missing, path: '{path}', method: '{method}'

Error message

operationId missing, path: '{path}', method: '{method}'

What it means

While iterating `paths` x methods, the parser requires each operation object to carry an `operationId`. If the key is absent it raises `PluginInitializationError` with the path and method. The connector uses `operationId` as the function name, so it must be present and unique.

Source

Thrown at python/semantic_kernel/connectors/openapi_plugin/openapi_parser.py:257

        elif servers:
            # Process servers, ensuring we capture their variables
            for server in servers:
                server_entry = {
                    "url": server.get("url", "/"),
                    "variables": server.get("variables", {}),
                    "description": server.get("description", ""),
                }
                server_urls.append(server_entry)
        else:
            # Default server if none specified
            server_urls = [{"url": "/", "variables": {}, "description": ""}]

        for path, methods in paths.items():
            for method, details in methods.items():
                request_method = method.lower()
                # Validate that operationId exists
                if "operationId" not in details:
                    raise PluginInitializationError(f"operationId missing, path: '{path}', method: '{method}'")
                operationId = details["operationId"]
                if operationId in unique_operation_ids_registered:
                    raise PluginInitializationError(
                        f"Duplicate operationId: '{operationId}', path: '{path}', method: '{method}'"
                    )
                unique_operation_ids_registered.add(operationId)

                summary = details.get("summary", None)
                description = details.get("description", None)

                # Exclude operations whose path would resolve to a different effective request target
                # than the one offered to the selection predicate: a dot-segment (encoded or literal)
                # or a non-relative (absolute / authority-changing) path. Excluding them here keeps
                # operation selection and request construction on one canonical target so such a path
                # cannot bypass an include/exclude operation-selection filter.
                if RestApiOperation._contains_dot_segment(path) or RestApiOperation._is_non_relative_path(path):
                    logger.warning(
                        f"Skipping operation {operationId} at path '{path}' because it does not resolve to a "

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Add a unique `operationId` to the offending operation in the spec.
2. Run a linter (e.g. Spectral with the `operation-operationId-unique` / `operationId` rules) to catch missing ids.
3. If you cannot edit the spec, pre-process it to synthesize ids (e.g. `{method}_{path}`) before loading.
4. Upgrade from Swagger 2.0 to OpenAPI 3.0 with a tool that backfills `operationId`.

Example fix

# before
paths:
  /pets/{id}:
    get:
      summary: Get a pet   # no operationId -> raises 1494

# after
paths:
  /pets/{id}:
    get:
      operationId: getPetById
      summary: Get a pet

def ops_missing_id(spec) -> list[str]:
    bad = []
    for path, methods in spec.get("paths", {}).items():
        for method, d in methods.items():
            if method.lower() not in {"get","post","put","patch","delete","head","options","trace"}:
                continue
            if "operationId" not in d:
                bad.append(f"{method} {path}")
    return bad

bad = ops_missing_id(spec)
assert not bad, bad

def has_operation_id(op_details) -> bool:
    return isinstance(op_details, dict) and bool(op_details.get("operationId"))

from semantic_kernel.exceptions import PluginInitializationError

try:
    kernel.add_openapi_plugin(plugin_name="x", openapi_parsed_spec=spec)
except PluginInitializationError as e:
    if "operationId missing" in str(e):
        # synthesize ids, then retry
        raise
    raise

When it happens

Trigger: An operation (path + HTTP method) in the spec without an `operationId` field. Common with specs authored for human-readable docs that relied on `summary` instead.

Common situations: Hand-written specs; specs exported from tools that omit `operationId` by default; OpenAPI 2.0 (Swagger) imports where `operationId` was optional; large specs where one endpoint was added quickly.

Related errors

• Parameter {name} is missing 'in' field
• Parameter {name} cannot have a 'content' field. Expected: sc
• Security scheme '{scheme_name}' is not defined in components
• Duplicate operationId: '{operationId}', path: '{path}', meth
• This `RestApiParameter` instance is frozen and cannot be mod

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