What causes "API VLM analysis returned empty description" in ATH-MaaS/Pixelle-Video?

Retry the analysis — empty responses are often transient provider issues

ATH-MaaS/Pixelle-Video · error · RuntimeError

API VLM analysis returned empty description

Error message

API VLM analysis returned empty description

What it means

_query_vlm str()s the VLM client result and raises RuntimeError if the trimmed description is empty — the API returned None, an empty string, or whitespace, so there is nothing useful to feed downstream.

Source

Thrown at pixelle_video/services/api_asset_analysis.py:172

        providers = self.config.get("api_providers", {}) or {}
        dashscope = providers.get("dashscope", {}) or {}

        client = VLM(
            dashscope_api_key=dashscope.get("api_key"),
            dashscope_base_url=dashscope.get("base_url"),
        )
        result = await asyncio.to_thread(
            client.query,
            prompt,
            image_paths,
            selected_model,
            None,
            video_paths,
        )
        description = str(result or "").strip()
        if not description:
            raise RuntimeError("API VLM analysis returned empty description")
        return description

    def _get_asset_type(self, path: Path) -> str:
        image_exts = {".jpg", ".jpeg", ".png", ".gif", ".webp"}
        video_exts = {".mp4", ".mov", ".avi", ".mkv", ".webm"}
        ext = path.suffix.lower()
        if ext in image_exts:
            return "image"
        if ext in video_exts:
            return "video"
        return "unknown"

View on GitHub (pinned to 848b054e4f)

Solutions

Retry the analysis — empty responses are often transient provider issues
Try a different/updated VLM model name supported by the provider
Check the provider logs/quota — safety filters or throttling often yield empty completions
Simplify the prompt passed to analyze_image/analyze_video

Example fix

# before
desc = await analyzer.analyze_image(path, model="some-vlm")
# after
try:
    desc = await analyzer.analyze_image(path, model="some-vlm")
except RuntimeError:
    desc = await analyzer.analyze_image(path, model="qwen-vl-max")  # fallback model

Defensive patterns

Strategy: retry

Validate before calling

# no pre-call validation possible; emptiness is only known after the API call

Type guard

def non_empty(value: object) -> bool:
    return bool(str(value or "").strip())

Try / catch

for attempt in range(3):
    try:
        return await analyzer.analyze_image(path, model=model)
    except RuntimeError as e:
        if "empty description" not in str(e):
            raise
        await asyncio.sleep(2 ** attempt)
raise RuntimeError("VLM returned empty description after retries")

Prevention

Retry transient empty responses with backoff
Log the raw provider response to distinguish filtering vs outages
Fall back to an alternate VLM model when the primary returns empty

When it happens

Trigger: The VLM API call completed but returned None/empty: model refused or produced no content for the prompt, API returned an empty completion, or result was not str-able to non-empty text.

Common situations: Prompt/safety filtering on the provider side; rate-limited or degraded API returning empty bodies; wrong model chosen that doesn't support image/video input and yields empty output; transient provider outage.

Related errors

AI-assisted analysis of ATH-MaaS/Pixelle-Video@848b054e4f (2026-08-30). Data as JSON: /api/errors/2040a17e94091442. Report an issue: GitHub.