ATH-MaaS/Pixelle-Video · error · HTTPException

str(e)

Error message

str(e)

What it means

The POST /narration handler catches any exception from narration generation and re-raises it as an HTTP 500 with the raw exception string as the detail. This is a catch-all: any failure inside the narration pipeline (LLM call, model config, serialization) surfaces as this opaque 500. The message is whatever str(e) produced, so it can be almost anything.

Source

Thrown at api/routers/content.py:75

    try:
        logger.info(f"Generating {request.n_scenes} narrations from text")
        
        # Call narration generator utility function
        narrations = await generate_narrations_from_topic(
            llm_service=pixelle_video.llm,
            topic=request.text,
            n_scenes=request.n_scenes,
            min_words=request.min_words,
            max_words=request.max_words
        )
        
        return NarrationGenerateResponse(
            narrations=narrations
        )
        
    except Exception as e:
        logger.error(f"Narration generation error: {e}")
        raise HTTPException(status_code=500, detail=str(e))


@router.post("/image-prompt", response_model=ImagePromptGenerateResponse)
async def generate_image_prompt(
    request: ImagePromptGenerateRequest,
    pixelle_video: PixelleVideoDep
):
    """
    Generate image prompts from narrations
    
    Uses LLM to create detailed image generation prompts.
    
    - **narrations**: List of narration texts
    - **min_words**: Minimum words per prompt
    - **max_words**: Maximum words per prompt
    
    Returns list of image prompts.
    """

View on GitHub (pinned to 848b054e4f)

Solutions

  1. Read the server log line 'Narration generation error: ...' — the detail is duplicated there with more context.
  2. Verify the AI provider API key/env vars are set and valid for narration generation.
  3. Call the narration generation path directly (script/tests) to reproduce the underlying exception outside the HTTP layer.
  4. Retry once if the log indicates a transient network/timeout error from the provider.
  5. Replace str(e) detail with a generic message and log the full traceback server-side to avoid leaking internals.

Example fix

// before
except Exception as e:
    logger.error(f"Narration generation error: {e}")
    raise HTTPException(status_code=500, detail=str(e))
// after
except Exception as e:
    logger.exception("Narration generation error")
    raise HTTPException(status_code=500, detail="Narration generation failed")
Defensive patterns

Strategy: try-catch

Validate before calling

if (!process.env.AI_API_KEY) throw new Error('AI provider API key not configured before calling narration endpoint');
const res = await fetch('/api/content/narration', { method: 'POST', body: JSON.stringify(req) });
if (res.status === 500) console.error('Narration generation failed; check server logs for root cause');

Try / catch

try {
  const res = await fetch('/api/content/narration', { method: 'POST', headers: {'Content-Type':'application/json'}, body: JSON.stringify(request) });
  if (!res.ok) {
    const detail = (await res.json()).detail;
    throw new Error(`Narration generation failed (500): ${detail}`);
  }
  return await res.json();
} catch (err) {
  logger.error('Narration request failed', err);
  throw err;
}

Prevention

When it happens

Trigger: POST to the narration endpoint where the underlying narration generation service raises any non-HTTPException error — e.g. missing/invalid AI provider API key, network failure to the LLM, malformed model output that fails response parsing, or an unexpected None/type error in the generation code.

Common situations: Missing or expired OPENAI/provider API key in the environment; the narration model returns JSON that fails validation; transient provider timeouts; a bug introduced in the generation service after a dependency upgrade.

Related errors

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