microsoft/semantic-kernel · error · FunctionExecutionException

Value '{value}' for server variable '{variable_name}' is not

Error message

Value '{value}' for server variable '{variable_name}' is not one of the allowed values.

What it means

After resolving a server URL variable's value (from argument or default), `get_server_url` checks it against the variable's `enum` constraint if one is declared in the OpenAPI spec. If the value is not in the allowed list, this FunctionExecutionException is raised. This enforces the OpenAPI `enum` restriction on server URL variables.

Source

Thrown at python/semantic_kernel/connectors/openapi_plugin/models/rest_api_operation.py:302

            server_url_string = server["url"] if isinstance(server, dict) else server
            server_variables = server.get("variables", {}) if isinstance(server, dict) else {}

            # Substitute server variables if available
            for variable_name, variable_def in server_variables.items():
                argument_name = variable_def.get("argument_name", variable_name)
                allowed_values = variable_def.get("enum")
                if argument_name in arguments:
                    value = str(arguments[argument_name])
                elif "default" in variable_def and variable_def["default"] is not None:
                    # Use the default value if no argument is provided
                    value = str(variable_def["default"])
                else:
                    # Raise an exception if no value is available
                    raise FunctionExecutionException(
                        f"No argument provided for the '{variable_name}' server variable of the operation '{self.id}'."
                    )
                if allowed_values is not None and value not in allowed_values:
                    raise FunctionExecutionException(
                        f"Value '{value}' for server variable '{variable_name}' is not one of the allowed values."
                    )
                server_url_string = server_url_string.replace(f"{{{variable_name}}}", quote(value, safe=""))
        elif self.server_url:
            server_url_string = self.server_url
        elif api_host_url is not None:
            server_url_string = api_host_url
        else:
            raise FunctionExecutionException(f"No valid server URL for operation {self.id}")

        # Ensure the base URL ends with a trailing slash
        if not server_url_string.endswith("/"):
            server_url_string += "/"

        return server_url_string  # Return the URL string directly

    def build_path(self, path_template: str, arguments: dict[str, Any]) -> str:
        """Build the path for the operation."""

View on GitHub (pinned to c028a0c7dc)

Solutions

Provide a value that is listed in the variable's `enum` constraint in the OpenAPI spec.
Check for case-sensitivity and match the exact allowed values.
Update the OpenAPI spec's `enum` to include the needed value if the restriction is too narrow.

Example fix

// before (region not in enum)
await api.call_op(region="asia")  # enum is [us, eu]
// after
await api.call_op(region="eu")

Defensive patterns

Strategy: validation

Validate before calling

def validate_server_variable_enum(operation, arguments: dict):
    for server in (operation.servers or []):
        for var_name, var_def in (server.get('variables') or {}).items():
            allowed = var_def.get('enum')
            if allowed is None:
                continue
            arg_name = var_def.get('argument_name', var_name)
            value = str(arguments.get(arg_name, var_def.get('default', '')))
            if value not in allowed:
                raise ValueError(f"Value '{value}' for '{var_name}' not in enum {allowed}")

Try / catch

try:
    result = await api.my_operation(**args)
except FunctionExecutionException as e:
    if "not one of the allowed values" in str(e):
        # provide a value from the variable's enum
        ...

Prevention

Check the variable's enum constraint in the spec and provide an allowed value.
Watch for case-sensitivity in enum values.
Update the spec's enum if a legitimate value is missing.

When it happens

Trigger: A server URL variable has an `enum` constraint in the OpenAPI spec, and the supplied argument value (or default) is not one of the allowed values. For example `enum: [us, eu]` but the caller passes `region="asia"`.

Common situations: Caller passes a region/zone/environment value not in the spec's allowed list. The spec's default value is incorrectly not in its own enum. Case-sensitivity mismatch (e.g. `US` vs `us`).

Related errors

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