huggingface/smolagents · error · ValueError

The space returned this message:

Error message

The space returned this message: 

What it means

When a Gradio Space endpoint returns a tuple/list whose second element is a string, smolagents treats that string as an error/status message from the Space and raises ValueError with it. Some Spaces signal failures (NSFW filter, rate limit, internal error) in the second tuple slot rather than raising.

Source

Thrown at src/smolagents/tools.py:721

                    (isinstance(arg, str) and os.path.isfile(arg))
                    or (isinstance(arg, Path) and arg.exists() and arg.is_file())
                    or is_http_url_like(arg)
                ):
                    arg = handle_file(arg)
                return arg

            def forward(self, *args, **kwargs):
                # Preprocess args and kwargs:
                args = list(args)
                for i, arg in enumerate(args):
                    args[i] = self.sanitize_argument_for_prediction(arg)
                for arg_name, arg in kwargs.items():
                    kwargs[arg_name] = self.sanitize_argument_for_prediction(arg)

                output = self.client.predict(*args, api_name=self.api_name, **kwargs)
                if isinstance(output, tuple) or isinstance(output, list):
                    if isinstance(output[1], str):
                        raise ValueError("The space returned this message: " + output[1])
                    output = output[
                        0
                    ]  # Sometime the space also returns the generation seed, in which case the result is at index 0
                IMAGE_EXTENSIONS = [".png", ".jpg", ".jpeg", ".gif", ".webp"]
                AUDIO_EXTENSIONS = [".mp3", ".wav", ".ogg", ".m4a", ".flac"]
                if isinstance(output, str) and any([output.endswith(ext) for ext in IMAGE_EXTENSIONS]):
                    output = AgentImage(output)
                elif isinstance(output, str) and any([output.endswith(ext) for ext in AUDIO_EXTENSIONS]):
                    output = AgentAudio(output)
                return output

        return SpaceToolWrapper(
            space_id=space_id,
            name=name,
            description=description,
            api_name=api_name,
            token=token,
        )

View on GitHub (pinned to 30bb116109)

Solutions

1. Wrap the tool call in try/except ValueError and inspect the message; retry after fixing the underlying cause (quota, NSFW flag, Space health)
2. Open the Space in the browser or test with gradio_client directly to see the raw output and confirm the failure reason
3. If the Space is healthy and this is a false positive from an extra string output, pick a different api_name or Space revision whose output layout matches

Example fix

# before
result = tool("a cat")
# after
try:
    result = tool("a cat")
except ValueError as e:
    # e.g. 'The space returned this message: GPU quota exceeded'
    logger.warning("Space error: %s", e)
    time.sleep(30)
    result = tool("a cat")

import time
from smolagents import Tool

def call_space_tool(tool: Tool, *args, retries: int = 2, **kwargs):
    for attempt in range(retries + 1):
        try:
            return tool(*args, sanitize_inputs_outputs=True, **kwargs)
        except ValueError as e:
            if attempt < retries and "space returned this message" in str(e).lower():
                time.sleep(10 * (attempt + 1))
                continue
            raise

When it happens

Trigger: Calling a SpaceToolWrapper created via Tool.from_space whose Space returns (result, "error message") tuples; queue full, GPU quota exceeded, safety filter triggered, or the Space returns (None, 'Error: ...').

Common situations: Using public Spaces that return status strings alongside results; ZeroGPU quota exhaustion; Space's endpoint signature changed so outputs are misaligned with the (result, status) expectation.

Related errors

• Could not find specified {api_name=} among available api nam
• 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 '
• The 'system_prompt' property is read-only. Use 'self.prompt_

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