microsoft/semantic-kernel · error · PluginInitializationError

Security scheme '{scheme_name}' is not defined in components

Error message

Security scheme '{scheme_name}' is not defined in components.

What it means

`_create_security_requirements` looks up each security scheme referenced by a requirement in `security_schemes` (sourced from `components.securitySchemes`). If the scheme name is missing there, it raises `PluginInitializationError`. The connector will not register an operation whose security it cannot resolve.

Source

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

            in_=security_scheme_data.get("in", ""),
            scheme=security_scheme_data.get("scheme", ""),
            bearer_format=security_scheme_data.get("bearerFormat"),
            flows=security_scheme_data.get("flows"),
            open_id_connect_url=security_scheme_data.get("openIdConnectUrl", ""),
        )

    def _create_security_requirements(
        self,
        security: list[dict[str, list[str]]],
        security_schemes: dict[str, dict],
    ) -> list[RestApiSecurityRequirement]:
        security_requirements: list[RestApiSecurityRequirement] = []

        for requirement in security:
            for scheme_name, scopes in requirement.items():
                scheme_data = security_schemes.get(scheme_name)
                if not scheme_data:
                    raise PluginInitializationError(f"Security scheme '{scheme_name}' is not defined in components.")
                scheme = self._create_rest_api_security_scheme(scheme_data)
                security_requirements.append(RestApiSecurityRequirement({scheme: scopes}))

        return security_requirements

    def create_rest_api_operations(
        self,
        parsed_document: Any,
        execution_settings: "OpenAPIFunctionExecutionParameters | None" = None,
    ) -> dict[str, RestApiOperation]:
        """Create REST API operations from the parsed OpenAPI document.

        Args:
            parsed_document: The parsed OpenAPI document.
            execution_settings: The execution settings.

        Returns:
            A dictionary of RestApiOperation instances.

View on GitHub (pinned to c028a0c7dc)

Solutions

1. Add the missing scheme to `components.securitySchemes` with the correct name.
2. Fix the typo so the requirement name exactly matches a defined scheme.
3. Bundle/dereference the spec so external `$ref`s resolve before loading.
4. Remove the security requirement if it is no longer relevant.

Example fix

# before
security:
  - oauth2: [read]      # raises 1493 if 'oauth2' not defined
components:
  securitySchemes:
    apiKey: { type: apiKey, in: header, name: X-API-KEY }

# after
security:
  - apiKey: []
components:
  securitySchemes:
    apiKey: { type: apiKey, in: header, name: X-API-KEY }

def dangling_security_refs(spec) -> list[str]:
    defined = set((spec.get("components") or {}).get("securitySchemes", {}))
    problems = []
    # global
    for req in spec.get("security", []):
        for name in req:
            if name not in defined:
                problems.append(f"global security: '{name}'")
    # per-op
    for path, methods in spec.get("paths", {}).items():
        for method, d in methods.items():
            for req in d.get("security", []):
                for name in req:
                    if name not in defined:
                        problems.append(f"{method} {path}: '{name}'")
    return problems

problems = dangling_security_refs(spec)
assert not problems, problems

def security_requirement_is_resolved(req, schemes) -> bool:
    return all(name in schemes for name in req)

from semantic_kernel.exceptions import PluginInitializationError

try:
    kernel.add_openapi_plugin(plugin_name="x", openapi_parsed_spec=spec)
except PluginInitializationError as e:
    if "not defined in components" in str(e):
        # add the missing scheme or drop the requirement, then retry
        raise
    raise

When it happens

Trigger: A `security` requirement (global or per-operation) referencing a scheme name that is not present in `components.securitySchemes`; a typo in the scheme name; schemes defined in a referenced file that was not bundled.

Common situations: Renaming a scheme in one place but not the other; splitting a spec into multiple files without bundling; copy-pasting a security requirement from another spec; specs where `components.securitySchemes` lives behind an unresolved `$ref`.

Related errors

• Parameter {name} is missing 'in' field
• Parameter {name} cannot have a 'content' field. Expected: sc
• operationId missing, path: '{path}', method: '{method}'
• Duplicate operationId: '{operationId}', path: '{path}', meth
• Call target node type '{type(node.func).__name__}' is not al

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