huggingface/smolagents · error · KeyError

Could not find specified {api_name=} among available api nam

Error message

Could not find specified {api_name=} among available api names.

What it means

When wrapping a Gradio Space with a specific api_name, smolagents looks up that endpoint in the Space's API description. If api_name doesn't match any endpoint, a KeyError is raised with the available names implied by the lookup.

Source

Thrown at src/smolagents/tools.py:674

                self.name = name
                self.description = description
                self.client = Client(space_id, hf_token=token)
                space_api = self.client.view_api(return_format="dict", print_info=False)
                assert isinstance(space_api, dict)
                space_description = space_api["named_endpoints"]

                # If api_name is not defined, take the first of the available APIs for this space
                if api_name is None:
                    api_name = list(space_description.keys())[0]
                    warnings.warn(
                        f"Since `api_name` was not defined, it was automatically set to the first available API: `{api_name}`."
                    )
                self.api_name = api_name

                try:
                    space_description_api = space_description[api_name]
                except KeyError:
                    raise KeyError(f"Could not find specified {api_name=} among available api names.")
                self.inputs = {}
                for parameter in space_description_api["parameters"]:
                    parameter_type = parameter["type"]["type"]
                    if parameter_type == "object":
                        parameter_type = "any"
                    self.inputs[parameter["parameter_name"]] = {
                        "type": parameter_type,
                        "description": parameter["python_type"]["description"],
                        "nullable": parameter["parameter_has_default"],
                    }
                output_component = space_description_api["returns"][0]["component"]
                if output_component == "Image":
                    self.output_type = "image"
                elif output_component == "Audio":
                    self.output_type = "audio"
                else:
                    self.output_type = "any"
                self.is_initialized = True

View on GitHub (pinned to 30bb116109)

Solutions

1. Omit api_name to let smolagents pick the first available endpoint
2. Get exact names via gradio_client.Client(repo).view_api() and pass one of those (usually with a leading slash, e.g. '/predict')
3. Pin the Space revision or use the direct space URL if the Space layout changed

Example fix

# before
tool = Tool.from_space("user/space", api_name="predict")
# after
from gradio_client import Client
print(Client("user/space").view_api())  # copy exact endpoint name
tool = Tool.from_space("user/space", api_name="/predict")

from gradio_client import Client
def get_api_names(repo_id: str) -> list[str]:
    return [ep.name() for ep in Client(repo_id).endpoints()]

names = get_api_names("user/space")
assert "/predict" in names before Tool.from_space("user/space", api_name="/predict")

try:
    tool = Tool.from_space(repo, api_name=name)
except KeyError:
    names = [ep.name() for ep in Client(repo).endpoints()]
    tool = Tool.from_space(repo, api_name=names[0])

When it happens

Trigger: Tool.from_space(repo_id, api_name="/predict2") where the Space exposes endpoints like '/predict'; using an api_name with a missing or extra leading slash; the Space changed its endpoint names after an update; hitting a Spaces router page instead of the direct Space URL.

Common situations: Passing the function name from Python ('predict') instead of the Gradio API path ('/predict'); Space author renamed endpoints; URL points to a Spaces router (e.g. huggingface.co/spaces/... redirects) so the wrong API description is fetched.

Related errors

• Cannot save objects created with from_space, from_langchain
• The space returned this message:
• Since `api_name` was not defined, it was automatically set t
• Error during jinja template rendering: {type(e).__name__}: {
• Cannot specify both 'messages' and 'steps' parameters. Use '

AI-assisted analysis of huggingface/smolagents@30bb116109 (2026-08-28). Data as JSON: /api/errors/31ea5a35cc1ddc16. Report an issue: GitHub.