BerriAI/litellm · error · ValueError

Invalid response format. Received response does not match th

Error message

Invalid response format. Received response does not match the expected format. Got:

What it means

After parsing, the WatsonX transcription transformer keeps only 'text' and 'usage' from the response JSON. If neither key is present, response_kwargs is empty and this ValueError fires. Quirk to know while debugging: the raise passes two arguments (message string, raw_response_json), so str(e) renders as a tuple and the 'Got: ' part of the printed message always looks empty - the actual payload is the second tuple element. An error payload like {"error": ...} with status 200 or an unexpected schema triggers it.

Source

Thrown at litellm/llms/watsonx/audio_transcription/transformation.py:188

        try:
            raw_response_json: Final = raw_response.json()
        except Exception as e:
            raise ValueError(f"Error transforming response to json: {e}\nResponse: {raw_response.text}")

        # Extract only valid fields for TranscriptionResponse.__init__()
        # TranscriptionResponse only accepts 'text' and 'usage' in __init__()
        text: Final = raw_response_json.get("text")
        usage: Final = raw_response_json.get("usage")

        # Create response with only valid fields
        response_kwargs: Final = {}
        if text is not None:
            response_kwargs["text"] = text
        if usage is not None:
            response_kwargs["usage"] = usage

        if not response_kwargs:
            raise ValueError(
                "Invalid response format. Received response does not match the expected format. Got: ",
                raw_response_json,
            )

        response: Final = TranscriptionResponse(**response_kwargs)

        # Add other fields using dictionary-style assignment (like duration, task, etc.)
        # Skip fields that TranscriptionResponse doesn't accept in __init__()
        for key, value in raw_response_json.items():
            if key not in [
                "text",
                "usage",
                "model",
            ]:  # text/usage already set, model should be excluded
                response[key] = value

        return response

View on GitHub (pinned to 77b7c6c40c)

Solutions

Inspect e.args[-1] (the second ValueError argument) - it holds the raw response dict that failed the shape check.
Verify the model and endpoint actually correspond to WatsonX speech-to-text; wrong endpoints return other shapes.
Print the payload once via litellm.set_verbose = True to see the real keys returned.
Pin/upgrade litellm if WatsonX changed its transcription response schema.

Example fix

# before
try:
    resp = litellm.transcription(model="watsonx/whisper-large-v3", file=f)
except ValueError as e:
    print(str(e))  # confusing tuple output, 'Got: ' looks empty

# after
try:
    resp = litellm.transcription(model="watsonx/whisper-large-v3", file=f)
except ValueError as e:
    raw = e.args[-1] if len(e.args) > 1 else None  # actual response dict
    logging.error("unexpected watsonx transcription payload: %r", raw)
    raise

Defensive patterns

Strategy: try-catch

Try / catch

try:
    resp = litellm.transcription(model="watsonx/whisper-large-v3", file=f)
except ValueError as e:
    if "Invalid response format" in str(e):
        raw = e.args[-1] if len(e.args) > 1 else None  # actual response dict (2-arg raise quirk)
        logging.error("unexpected watsonx payload: %r", raw)
        raise UpstreamContractError("watsonx transcription schema mismatch") from e
    raise

Prevention

Remember the two-arg ValueError: the real payload is in e.args[-1], not in the message text.
Pin litellm and WatsonX speech API versions you tested together.
Log full payloads (sampled) in staging to detect schema drift early.

When it happens

Trigger: WatsonX returns a JSON error body (missing/invalid fields) with status 200; endpoint version drift returning e.g. {"results": ...} instead of {"text": ...}; empty JSON {} from a gateway; responses where the transcription text key was renamed.

Common situations: Migrating between WatsonX speech API versions; custom api_base gateways rewrapping payloads; silent quota/auth errors delivered as 200 with an error JSON.

Related errors

AI-assisted analysis of BerriAI/litellm@77b7c6c40c (2026-08-18). Data as JSON: /api/errors/34891fee392fb219. Report an issue: GitHub.